sevgi-graphics 0.94.0 → 0.98.2

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

@@ -5,15 +5,17 @@ module Sevgi
     module Mixtures
       # DSL helpers for collecting and hiding SVG ids.
       module Identify
-        # Index of element ids under a subtree.
+        # Immutable snapshot of every rendered element id under a subtree. Keys are the serialized id values, including
+        # `"false"` and the empty String. Keys and containers are owned by the index; values retain references to the
+        # elements present when the snapshot is built. Later tree changes require a new index.
         class Identifiers
           # @return [Sevgi::Graphics::Element] indexed root element
           attr_reader :element
 
-          # @return [Hash<String, Sevgi::Graphics::Element>] id namespace
+          # @return [Hash<String, Sevgi::Graphics::Element>] frozen namespace keyed by serialized rendered ids
           attr_reader :namespace
 
-          # @return [Hash<String, Array<Sevgi::Graphics::Element>>] duplicate id groups
+          # @return [Hash<String, Array<Sevgi::Graphics::Element>>] frozen duplicate groups keyed by serialized ids
           attr_reader :collision
 
           # Builds an id index for an element subtree.
@@ -25,6 +27,10 @@ module Sevgi
             @collision = {}
 
             build
+            @namespace.freeze
+            @collision.each_value(&:freeze)
+            @collision.freeze
+            freeze
           end
 
           # Reports whether duplicate ids were found.
@@ -33,21 +39,20 @@ module Sevgi
             !@collision.empty?
           end
 
-          # @overload [](id)
-          #   Returns the element registered for an id.
-          #   @param id [String] SVG id
-          #   @return [Sevgi::Graphics::Element, nil]
-          def [](*)
-            @namespace[*]
-          end
+          # Returns the first element registered for an id in the snapshot.
+          # Duplicate entries are available through {#collision}.
+          # @param id [String] serialized rendered SVG id
+          # @return [Sevgi::Graphics::Element, nil]
+          def [](id) = @namespace[id]
 
           private
 
           def build
             element.Traverse() do |element|
-              next unless (value = element[:id])
+              next unless element.attributes.has?(:id)
 
-              id = Attribute.xml_text(value)
+              value = element[:id]
+              id = Attribute.xml_text(value).dup.freeze
 
               if @namespace.key?(id)
                 (@collision[id] ||= [@namespace[id]]) << element
@@ -58,18 +63,26 @@ module Sevgi
           end
         end
 
-        # Moves visible id attributes to Sevgi-internal id storage.
+        # Moves visible id attributes to non-rendering `-id` metadata throughout the subtree.
+        # A pre-existing `-id` takes precedence over the visible id.
         # @return [Sevgi::Graphics::Element] self
+        # @example Hide ids while retaining their source identity
+        #   document = Sevgi::Graphics.SVG { rect id: "source-id" }
+        #   document.Disidentify
+        #   document.children.first[:"-id"] # => "source-id"
         def Disidentify
           Traverse do |element|
-            next unless element[:id]
+            next unless element.attributes.has?(:id)
 
-            element[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = element.attributes.delete(:id)
+            id = element.attributes.delete(:id)
+            metadata = :"#{Attributes::META_PREFIX}id"
+            element[metadata] = id unless element.attributes.has?(metadata)
           end
         end
 
-        # Builds an id index for this element subtree.
-        # @return [Sevgi::Graphics::Mixtures::Identify::Identifiers]
+        # Builds an immutable id index snapshot for the current element subtree.
+        # Rebuild the index to observe later id or tree changes.
+        # @return [Sevgi::Graphics::Mixtures::Identify::Identifiers] new snapshot retaining indexed element references
         def Identifiers = Identifiers.new(self)
       end
     end

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

@@ -4,6 +4,33 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for including derendered SVG/XML fragments.
+      #
+      # @!method Include(file, id, omit: nil)
+      #   Includes a derendered node matching an id.
+      #   SVG/XML content is treated as data and is not evaluated as Ruby source.
+      #   @example Import a fragment without editor ids and inline styles
+      #     Sevgi::Graphics.SVG do
+      #       Include "badge.svg", "mark", omit: %i[id style]
+      #     end
+      #   @param file [String] source SVG/XML file
+      #   @param id [String, Symbol] source node id
+      #   @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+      #     subtree after id selection
+      #   @return [Sevgi::Graphics::Element, nil] included element, or nil when it produces no graphics output
+      #   @raise [Sevgi::ArgumentError] when the file is absent or XML content is malformed, rootless, or lacks the id
+      #   @raise [SystemCallError] when the file cannot be read
+      #   @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
+      # @!method IncludeChildren(file, id, omit: nil)
+      #   Includes the children of a derendered node matching an id.
+      #   SVG/XML content is treated as data and is not evaluated as Ruby source.
+      #   @param file [String] source SVG/XML file
+      #   @param id [String, Symbol] source node id
+      #   @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+      #     subtree after id selection
+      #   @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+      #   @raise [Sevgi::ArgumentError] when the file is absent or XML content is malformed, rootless, or lacks the id
+      #   @raise [SystemCallError] when the file cannot be read
+      #   @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
       module Include
         require "sevgi/derender"
 
@@ -12,38 +39,46 @@ module Sevgi
         # SVG/XML file content is treated as data and is not evaluated as Ruby source.
         # @param file [String] source SVG/XML file
         # @param id [String, Symbol] source node id
+        # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+        #   subtree after id selection
         # @return [Sevgi::Graphics::Element, nil] included element, or nil when the selected node produces no graphics
         #   output
         # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
         #   absent
+        # @raise [SystemCallError] when the file cannot be read
         # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
-        def Include(file, id) = Derender.evaluate_file(file, self, id:)
+        def Include(file, id, omit: nil) = Derender.evaluate_file(file, self, id:, omit:)
 
         # Includes the children of a derendered node matching an id.
         #
         # SVG/XML file content is treated as data and is not evaluated as Ruby source.
         # @param file [String] source SVG/XML file
         # @param id [String, Symbol] source node id
-        # @return [Array<Sevgi::Graphics::Element>] included children
+        # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+        #   subtree after id selection
+        # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
         # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
         #   absent
+        # @raise [SystemCallError] when the file cannot be read
         # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
-        def IncludeChildren(file, id) = Derender.evaluate_file_children(file, self, id:)
+        def IncludeChildren(file, id, omit: nil) = Derender.evaluate_children_file(file, self, id:, omit:)
       rescue ::LoadError => e
         raise unless e.path == "sevgi/derender"
 
-        # @overload IncludeChildren(file, id)
+        # @overload IncludeChildren(file, id, omit: nil)
         #   Raises because sevgi/derender is unavailable.
         #   @param file [String] source SVG/XML file
         #   @param id [String, Symbol] source node id
+        #   @param omit [String, Symbol, Array<String, Symbol>, nil] ignored because the component is unavailable
         #   @return [void]
         #   @raise [Sevgi::MissingComponentError] always
         def IncludeChildren(...) = MissingComponentError.("sevgi/derender")
 
-        # @overload Include(file, id)
+        # @overload Include(file, id, omit: nil)
         #   Raises because sevgi/derender is unavailable.
         #   @param file [String] source SVG/XML file
         #   @param id [String, Symbol] source node id
+        #   @param omit [String, Symbol, Array<String, Symbol>, nil] ignored because the component is unavailable
         #   @return [void]
         #   @raise [Sevgi::MissingComponentError] always
         def Include(...) = MissingComponentError.("sevgi/derender")

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

@@ -5,6 +5,22 @@ module Sevgi
     module Mixtures
       # Inkscape-specific SVG DSL helpers.
       module Inkscape
+        # Normalizes callable wrapper attributes outside the DSL method surface.
+        # @api private
+        module Wrapper
+          # Returns owned wrapper attributes with a stable default id when the module is named.
+          # @param mod [Module] callable drawing module
+          # @param attributes [Hash] wrapper attributes
+          # @return [Hash{Symbol => Object}] normalized attributes
+          # @raise [Sevgi::ArgumentError] when attributes contains colliding names
+          def self.attributes(mod, attributes)
+            defaults = mod.name ? {id: F.demodulize(mod.name).to_sym} : {}
+            Attribute.defaults(attributes, **defaults)
+          end
+        end
+
+        private_constant :Wrapper
+
         # Adds Inkscape template metadata.
         # @param name [String] template name
         # @param desc [String, nil] short description
@@ -23,41 +39,67 @@ module Sevgi
         end
 
         # Renders a callable module inside a group.
-        # @param mod [Module] callable drawing module
+        # Named modules default the group id to their final constant name. Anonymous modules omit the id unless supplied.
+        # @example Supply a stable id for an anonymous callable
+        #   drawing = Module.new do
+        #     extend Sevgi::Graphics::Module
+        #     def call = circle r: 5
+        #   end
+        #   Sevgi::Graphics.SVG(:inkscape) { Group drawing, attributes: {id: "drawing"} }
+        # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param kwargs [Hash] group attributes
+        # @param attributes [Hash] group attributes; String and Symbol names are normalized and must not collide
+        # @param kwargs [Hash] callable keyword arguments
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] group element
-        # @raise [Sevgi::ArgumentError] when mod is not a plain module
-        def Group(mod, *args, **kwargs, &block)
-          kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
-          g(**kwargs) { Call(mod, *args, &block) }
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module or attributes is not a Hash
+        def Group(mod, *args, attributes: {}, **kwargs, &block)
+          Graphics::Module.__send__(:callables, mod)
+          ArgumentError.("Group attributes must be a Hash") unless attributes.is_a?(::Hash)
+          attributes = Wrapper.attributes(mod, attributes)
+          g(**attributes) { Call(mod, *args, **kwargs, &block) }
         end
 
         # Renders a callable module inside an Inkscape layer.
-        # @param mod [Module] callable drawing module
+        # Named modules default the layer id to their final constant name. Anonymous modules omit the id unless supplied.
+        # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param kwargs [Hash] layer attributes
+        # @param attributes [Hash] layer attributes; String and Symbol names are normalized and must not collide
+        # @param kwargs [Hash] callable keyword arguments
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] layer element
-        # @raise [Sevgi::ArgumentError] when mod is not a plain module
-        def Layer(mod, *args, **kwargs, &block)
-          kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
-          layer(**kwargs) { Call(mod, *args, &block) }
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module or attributes is not a Hash
+        def Layer(mod, *args, attributes: {}, **kwargs, &block)
+          Graphics::Module.__send__(:callables, mod)
+          ArgumentError.("Layer attributes must be a Hash") unless attributes.is_a?(::Hash)
+          attributes = Wrapper.attributes(mod, attributes)
+          layer(**attributes) { Call(mod, *args, **kwargs, &block) }
         end
 
         # Renders a callable module inside an insensitive Inkscape layer.
-        # @param mod [Module] callable drawing module
+        # Named modules default the layer id to their final constant name. Anonymous modules omit the id unless supplied.
+        # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param kwargs [Hash] layer attributes
+        # @param attributes [Hash] layer attributes; String and Symbol names are normalized and must not collide
+        # @param kwargs [Hash] callable keyword arguments
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] layer element
-        # @raise [Sevgi::ArgumentError] when mod is not a plain module
-        def Layer!(mod, *args, **kwargs, &block)
-          kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
-          layer!(**kwargs) { Call(mod, *args, &block) }
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module or attributes is not a Hash
+        def Layer!(mod, *args, attributes: {}, **kwargs, &block)
+          Graphics::Module.__send__(:callables, mod)
+          ArgumentError.("Layer attributes must be a Hash") unless attributes.is_a?(::Hash)
+          attributes = Wrapper.attributes(mod, attributes)
+          layer!(**attributes) { Call(mod, *args, **kwargs, &block) }
         end
 
         # @overload layer(**attributes)
         #   Builds an Inkscape layer group.
         #   @param attributes [Hash] layer attributes
+        #   @yield evaluates the drawing DSL in the layer
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] layer group
         def layer(**, &block)
           g("inkscape:groupmode": "layer", **, &block)
@@ -66,51 +108,178 @@ module Sevgi
         # @overload layer!(**attributes)
         #   Builds an insensitive Inkscape layer group.
         #   @param attributes [Hash] layer attributes
+        #   @yield evaluates the drawing DSL in the layer
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] layer group
         def layer!(**, &block)
           layer("sodipodi:insensitive": "true", **, &block)
         end
 
-        # Builds an Inkscape namedview containing page elements.
-        # @param pages [Array<Hash>] page attribute hashes
-        # @param id [String] namedview id
-        # @return [Sevgi::Graphics::Element] namedview element
-        def Pages(*pages, id: "namedview", **, &block)
-          Element(:"sodipodi:namedview", id:, **) do
-            pages.each_with_index do |page, i|
-              id = page[:id] || "page-#{i + 1}"
-              x, y, width, height = page.values_at(*%i[x y width height])
-              element = Element(:"inkscape:page", id:, x:, y:, width:, height:)
-              yield(element) if block
+        # Validates and constructs Inkscape page collections outside the DSL method surface.
+        # @api private
+        module Pagination
+          class << self
+            # Builds a namedview from normalized page attributes.
+            # @param context [Sevgi::Graphics::Element] DSL element receiving the namedview
+            # @param pages [Array<Hash>] page attributes
+            # @param namedview [Hash] namedview attributes
+            # @param page [Hash] shared page attributes
+            # @return [Sevgi::Graphics::Element] namedview element
+            # @raise [Sevgi::ArgumentError] when an attribute channel or page is invalid
+            def call(context, pages, namedview:, page:, &block)
+              namedview, page = channels(namedview, page)
+              pages = pages.each_with_index.map { |attributes, index| normalize(attributes, page, index) }
+
+              context.Element(:"sodipodi:namedview", **namedview) do
+                pages.each do |attributes|
+                  element = Element(:"inkscape:page", **attributes)
+                  block&.call(element)
+                end
+              end
+            end
+
+            # Generates validated attributes for a rectangular page grid.
+            # @return [Array<Hash{Symbol => Object}>] page attribute hashes
+            # @raise [Sevgi::ArgumentError] when a count, dimension, or gap is invalid
+            def tabular(rows:, cols:, width:, height:, gap:)
+              width, height, gap = normalize_grid(rows:, cols:, width:, height:, gap:)
+
+              rows.times.flat_map do |row|
+                cols.times.map do |col|
+                  x = col * (width + gap)
+                  y = row * (height + gap)
+                  label = "#{row + 1}x#{col + 1}"
+                  {id: "pageview-#{label}", x:, y:, width:, height:}
+                end
+              end
+            end
+
+            private
+
+            # Validates and normalizes the namedview and page-default channels.
+            # @return [Array<Hash>] normalized namedview attributes and page defaults
+            # @raise [Sevgi::ArgumentError] when either channel is not a Hash or has invalid attributes
+            # @api private
+            def channels(namedview, page)
+              ArgumentError.("Namedview attributes must be a Hash") unless namedview.is_a?(::Hash)
+              ArgumentError.("Page attributes must be a Hash") unless page.is_a?(::Hash)
+              [Attribute.defaults(namedview, id: "namedview"), Attribute.normalize(page)]
+            end
+
+            # Normalizes one explicit or generated page id.
+            # @return [Hash{String, Symbol => Object}] attributes beginning with a canonical id
+            # @raise [Sevgi::ArgumentError] when String and Symbol ids collide
+            # @api private
+            def identify(attributes, index)
+              id = attributes.key?(:id) ? attributes.delete(:id) : "page-#{index + 1}"
+              {id:}.merge(attributes)
+            end
+
+            # Normalizes and validates one page.
+            # @return [Hash{String, Symbol => Object}] independent page attributes
+            # @raise [Sevgi::ArgumentError] when attributes or dimensions are invalid
+            # @api private
+            def normalize(attributes, defaults, index)
+              ArgumentError.("Page #{index + 1} must be a Hash") unless attributes.is_a?(::Hash)
+              attributes = defaults.merge(Attribute.normalize(attributes))
+              %i[x y].each { number(attributes, it, index) }
+              %i[width height].each do |field|
+                number(attributes, field, index, positive: true)
+              end
+
+              identify(attributes, index)
+            end
+
+            # Validates and normalizes page-grid arguments.
+            # @return [Array<(Integer, Float)>] normalized width, height, and gap
+            # @raise [Sevgi::ArgumentError] when a count, dimension, or gap is invalid
+            # @api private
+            def normalize_grid(rows:, cols:, width:, height:, gap:)
+              {rows:, cols:}.each do |field, count|
+                unless count.is_a?(::Integer) && count.positive?
+                  ArgumentError.("Page #{field} must be a positive Integer")
+                end
+              end
+
+              [
+                Scalar.number(width, context: "page", field: :width, positive: true),
+                Scalar.number(height, context: "page", field: :height, positive: true),
+                Scalar.number(gap, context: "page", field: :gap, nonnegative: true)
+              ]
+            end
+
+            # Replaces one page field with its normalized SVG number.
+            # @return [Integer, Float] normalized number
+            # @api private
+            def number(attributes, field, index, **range)
+              key = attributes.key?(field) ? field : field.to_s
+              attributes[key] = Scalar.number(value(attributes, field, index), context: "page", field:, **range)
+            end
+
+            # Returns one required page field.
+            # @return [Object] page field value
+            # @raise [Sevgi::ArgumentError] when the field is absent
+            # @api private
+            def value(attributes, field, index)
+              attributes.fetch(field) do
+                attributes.fetch(field.to_s) { ArgumentError.("Page #{index + 1} requires #{field}") }
+              end
             end
           end
         end
 
+        private_constant :Pagination
+
+        # Builds an Inkscape namedview containing page elements.
+        # @example Build explicit pages with separate namedview and page attributes
+        #   Sevgi::Graphics.SVG(:inkscape) do
+        #     Pages(
+        #       {x: 0, y: 0, width: 100, height: 50, label: "front"},
+        #       namedview: {id: "views"},
+        #       page: {class: "print"}
+        #     )
+        #   end
+        # @param pages [Array<Hash>] page attribute hashes; numeric page fields are normalized to SVG numbers
+        # @param namedview [Hash] namedview attributes; String and Symbol names are normalized and must not collide
+        # @param page [Hash] page defaults; normalized page attributes override these defaults by name
+        # @yield [page] customizes each generated page element
+        # @yieldparam page [Sevgi::Graphics::Element] generated page element
+        # @yieldreturn [Object] ignored customization result
+        # @return [Sevgi::Graphics::Element] namedview element
+        # @raise [Sevgi::ArgumentError] when an attribute channel, page, coordinate, or dimension is invalid
+        def Pages(*pages, namedview: {}, page: {}, &block) = Pagination.call(self, pages, namedview:, page:, &block)
+
         # Builds a tabular set of Inkscape pages.
+        # @example Build a page grid using the same attribute channels as {#Pages}
+        #   Sevgi::Graphics.SVG(:inkscape) do
+        #     PagesTabular(
+        #       rows: 2, cols: 3, width: 100, height: 50, gap: 5,
+        #       namedview: {id: "views"}, page: {class: "print"}
+        #     )
+        #   end
         # @param rows [Integer] number of rows
         # @param cols [Integer] number of columns
-        # @param width [Numeric] page width
-        # @param height [Numeric] page height
-        # @param gap [Numeric] gap between pages
-        # @param id [String] namedview id
-        # @return [Array<Array>] matrix entries as x, y, and label tuples
-        def PagesTabular(rows:, cols:, width:, height:, gap:, id: "namedview", **)
-          [].tap do |matrix|
-            Element(:"sodipodi:namedview", id:) do
-              rows.times do |row|
-                cols.times do |col|
-                  matrix << (x, y, label = col * (width + gap), row * (height + gap), "#{row + 1}x#{col + 1}")
-                  Element(:"inkscape:page", id: "pageview-#{label}", x:, y:, width:, height:, **)
-                end
-              end
-            end
-          end
+        # @param width [Numeric] finite positive page width, normalized to an SVG number
+        # @param height [Numeric] finite positive page height, normalized to an SVG number
+        # @param gap [Numeric] finite non-negative gap, normalized to an SVG number
+        # @param namedview [Hash] namedview attributes; String and Symbol names are normalized and must not collide
+        # @param page [Hash] page defaults; normalized page attributes override these defaults by name
+        # @yield [page] customizes each generated page element
+        # @yieldparam page [Sevgi::Graphics::Element] generated page element
+        # @yieldreturn [Object] ignored customization result
+        # @return [Sevgi::Graphics::Element] namedview element
+        # @raise [Sevgi::ArgumentError] when counts, dimensions, gap, or an attribute channel is invalid
+        # @see #Pages
+        def PagesTabular(rows:, cols:, width:, height:, gap:, namedview: {}, page: {}, &block)
+          pages = Pagination.tabular(rows:, cols:, width:, height:, gap:)
+          Pages(*pages, namedview:, page:, &block)
         end
 
-        # Internal symbol which does not show up Symbols Menu
         # @overload symbol!(**attributes)
         #   Builds an Inkscape symbol group hidden from the symbols menu.
         #   @param attributes [Hash] symbol attributes
+        #   @yield evaluates the drawing DSL in the symbol group
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] symbol group
         def symbol!(**, &block)
           if Is?(:defs)