sevgi-graphics 0.73.2 → 0.93.1

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

@@ -5,11 +5,47 @@ require "forwardable"
 module Sevgi
   module Graphics
     module Mixtures
+      # Internal traversal stop token.
+      # @api private
+      Traversal = Data.define(:value) do
+        # Runs a depth-first traversal.
+        # @param element [Sevgi::Graphics::Element] starting element
+        # @param depth [Integer] starting depth
+        # @param leave [Proc, nil] optional leave callback
+        # @return [Sevgi::Graphics::Element, Object]
+        def self.call(element, depth, leave, &block)
+          catch(:traversal) do
+            visit(element, depth, leave, &block)
+            element
+          end
+        end
+
+        def self.stop(value)
+          throw(:traversal, value.value) if value.is_a?(self)
+        end
+
+        def self.visit(element, depth, leave, &block)
+          stop(block.call(element, depth))
+          element.children.each { |child| visit(child, depth + 1, leave, &block) }
+          stop(leave.call(element, depth)) if leave
+        end
+
+        private_class_method :stop, :visit
+      end
+
+      private_constant :Traversal
+
+      # Core SVG tree and attribute DSL helpers.
       module Core
         extend Forwardable
         def_delegators :@attributes, :[], :[]=, :has?
         def_delegators :@children, :first, :last, :at
 
+        # Moves this element under a new parent.
+        # @param new_parent [Sevgi::Graphics::Element, nil] target parent or current parent
+        # @param index [Integer] insertion index
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when the target parent has a different element class
         def Adopt(new_parent = nil, index: -1)
           tap do
             if new_parent
@@ -25,89 +61,131 @@ module Sevgi
           end
         end
 
+        # @overload AdoptFirst(new_parent = nil)
+        #   Moves this element to the beginning of a parent.
+        #   @param new_parent [Sevgi::Graphics::Element, nil] target parent or current parent
+        #   @return [Sevgi::Graphics::Element] self
         def AdoptFirst(*)
           Adopt(*, index: 0)
         end
 
+        # Appends existing elements as children.
+        # @param elements [Array<Sevgi::Graphics::Element>] elements to append
+        # @return [Sevgi::Graphics::Element] self
         def Append(*elements)
           tap { elements.each { it.Adopt(self) } }
         end
 
+        # Adds CSS classes without duplicating existing values.
+        # @param classes [Array<String, Symbol>] class names
+        # @return [Sevgi::Graphics::Element] self
         def Classify(*classes)
           tap do
-            unless self[:class]
-              self[:class] = classes
-              next
-            end
-
-            case self[:class]
+            klasses = case self[:class]
             when ::Array
               self[:class]
             when ::String
               self[:class].split
-            end => klasses
+            when nil
+              []
+            else
+              [self[:class]]
+            end
 
             classes.each { klasses << it unless klasses.include?(it) }
+            self[:class] = klasses
           end
         end
 
+        # Assigns default attributes only when they are absent.
+        # @param attributes [Hash] default attributes
+        # @return [Sevgi::Graphics::Element] self
         def Defaults(**attributes)
           tap do
             attributes.each do |key, value|
-              next if self[key]
+              next if has?(key)
 
               self[key] = value
             end
           end
         end
 
+        # Builds a child element with an explicit tag name.
+        # @param tag [Symbol, String] SVG tag name
+        # @param contents [Array<Object>] text or content objects
+        # @param attributes [Hash] SVG attributes
+        # @return [Sevgi::Graphics::Element] new child element
         def Element(tag, *contents, **attributes, &block)
           self.class.send(:new, tag.to_sym, contents: Content.contents(*contents), attributes:, parent: self, &block)
         end
 
+        # Forwards this element as the first argument to another receiver.
+        # @overload Forward(receiver, method, *args, **kwargs)
+        #   @param receiver [Object] target receiver
+        #   @param method [Symbol, String] method name
+        #   @param args [Array<Object>] additional arguments
+        #   @param kwargs [Hash] additional keyword arguments
+        #   @return [Object] forwarded call result
         def Forward(receiver, method, ...)
           receiver.public_send(method, self, ...)
         end
 
+        # Reports whether this element has the given SVG name.
+        # @param name [Symbol, String] SVG name
+        # @return [Boolean]
         def Is?(name)
           self.name() == name.to_sym
         end
 
+        # Removes this element from its parent.
+        # @return [Array<Sevgi::Graphics::Element>, nil] parent children after deletion, or nil for root elements
         def Orphan
           parent.children&.delete(self) unless Root?()
         end
 
+        # Prepends existing elements as children.
+        # @param elements [Array<Sevgi::Graphics::Element>] elements to prepend
+        # @return [Sevgi::Graphics::Element] self
         def Prepend(*elements)
           tap { elements.each { it.AdoptFirst(self) } }
         end
 
+        # Returns the root document element.
+        # @return [Sevgi::Graphics::Element]
         def Root
           element = self
-          element = element.parent while element.Root?()
+          element = element.parent until element.Root?()
 
           element
         end
 
+        # Reports whether this element is the root document element.
+        # @return [Boolean]
         def Root?
           self.class.root?(self)
         end
 
-        Traversal = Data.define(:value)
-
+        # @overload Stay(value)
+        #   Wraps a traversal return value as a stop token.
+        #   @param value [Object] value returned from traversal
+        #   @return [Sevgi::Graphics::Mixtures::Traversal]
         def Stay(...) = Traversal.new(...)
 
+        # Traverses the subtree depth-first.
+        # @param depth [Integer] starting depth
+        # @param leave [Proc, nil] optional leave callback
+        # @return [Sevgi::Graphics::Element, Object] self or the value passed through Stay
+        # @raise [Sevgi::ArgumentError] when no block is given
         def Traverse(depth = 0, leave = nil, &block)
           ArgumentError.("Block required") unless block
 
-          tap do
-            yield(self, depth).tap { return it.value if it.is_a?(Traversal) }
-
-            children.each { |child| child.Traverse(depth + 1, leave, &block) }
-
-            leave&.call(self, depth).tap { return it.value if it.is_a?(Traversal) }
-          end
+          Traversal.call(self, depth, leave, &block)
         end
 
+        # Traverses ancestors from this element to the root.
+        # @param height [Integer] starting height
+        # @return [Object, nil] value passed through Stay, or nil
+        # @raise [Sevgi::ArgumentError] when no block is given
         def TraverseUp(height = 0, &block)
           ArgumentError.("Block required") unless block
 
@@ -123,14 +201,25 @@ module Sevgi
           end
         end
 
+        # Evaluates a block in the parent element context.
+        # @param args [Array<Object>] optional receiver override followed by block arguments
+        # @param kwargs [Hash] keyword arguments passed to the block
+        # @return [Sevgi::Graphics::Element] self
         def With(*args, **kwargs, &block)
           tap { (args.shift || self).parent.instance_exec(*args, **kwargs, &block) }
         end
 
+        # Evaluates a block in this element context.
+        # @param args [Array<Object>] optional receiver override followed by block arguments
+        # @param kwargs [Hash] keyword arguments passed to the block
+        # @return [Sevgi::Graphics::Element] self
         def Within(*args, **kwargs, &block)
           tap { (args.shift || self).instance_exec(*args, **kwargs, &block) }
         end
 
+        # Appends an element as a child.
+        # @param element [Sevgi::Graphics::Element] element to append
+        # @return [Sevgi::Graphics::Element] self
         def <<(element)
           Append(element)
         end

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

@@ -3,7 +3,13 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for duplicating elements and their subtrees.
       module Duplicate
+        # Duplicates an element subtree and optionally translates it.
+        # @param dx [Numeric, nil] x translation
+        # @param dy [Numeric, nil] y translation
+        # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # @return [Sevgi::Graphics::Element] duplicated element
         def Duplicate(dx: nil, dy: nil, parent: nil, &block)
           duplicated = dup
 
@@ -21,8 +27,16 @@ module Sevgi
           duplicated
         end
 
+        # Duplicates an element subtree along the x-axis.
+        # @param dx [Numeric] x translation
+        # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # @return [Sevgi::Graphics::Element] duplicated element
         def DuplicateX(dx, parent: nil, &block) = Duplicate(dx:, dy: 0, parent:, &block)
 
+        # Duplicates an element subtree along the y-axis.
+        # @param dy [Numeric] y translation
+        # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # @return [Sevgi::Graphics::Element] duplicated element
         def DuplicateY(dy, parent: nil, &block) = Duplicate(dx: 0, dy:, parent:, &block)
       end
     end

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

@@ -3,21 +3,44 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for native SVG export formats.
       module Export
+        # Exports the document as PDF.
+        # @param path [String, nil] output path or directory
+        # @param kwargs [Hash] export options
+        # @return [String] output path
+        # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
+        # @raise [Sevgi::Sundries::ExportError] when native export fails
         def PDF(path = nil, **kwargs, &block)
-          require "sevgi/sundries"
+          begin
+            require "sevgi/sundries"
+
+          rescue ::LoadError => e
+            raise unless e.path == "sevgi/sundries"
+
+            MissingComponentError.("sevgi/sundries")
+          end
 
           Export(path, **kwargs, format: :pdf, &block)
-        rescue ::LoadError
-          raise NoMethodError, "\"sevgi/sundries\" required"
         end
 
+        # Exports the document as PNG.
+        # @param path [String, nil] output path or directory
+        # @param kwargs [Hash] export options
+        # @return [String] output path
+        # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
+        # @raise [Sevgi::Sundries::ExportError] when native export fails
         def PNG(path = nil, **kwargs, &block)
-          require "sevgi/sundries"
+          begin
+            require "sevgi/sundries"
+
+          rescue ::LoadError => e
+            raise unless e.path == "sevgi/sundries"
+
+            MissingComponentError.("sevgi/sundries")
+          end
 
           Export(path, **kwargs, format: :png, &block)
-        rescue ::LoadError
-          raise NoMethodError, "\"sevgi/sundries\" required"
         end
 
         private

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

@@ -3,14 +3,35 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for drawing geometry-derived hatch lines.
       module Hatch
+        # Draws one or more geometry line-like objects into this element.
+        # @param lines [Object, Array<Object>] drawable geometry objects
+        # @param kwargs [Hash] SVG attributes passed to each draw call
+        # @return [Array<Sevgi::Graphics::Element>] rendered line elements
         def Draw(lines, **kwargs)
           Array(lines).map { it.draw(self, **kwargs) }
         end
 
-        # TODO: angle vs direction
-        def Hatch(element, direction:, step:, initial: nil, **kwargs)
-          Draw(Geometry::Operation.sweep!(element, initial: initial || element.position, direction:, step:), **kwargs)
+        # Draws hatch lines swept through a geometry element.
+        # @param element [Object] geometry element responding to position
+        # @param angle [Numeric] hatch angle in degrees
+        # @param step [Numeric] distance between hatch lines
+        # @param initial [Object, nil] initial point for the sweep
+        # @param kwargs [Hash] SVG attributes passed to each draw call
+        # @return [Array<Sevgi::Graphics::Element>] rendered line elements
+        # @raise [Sevgi::MissingComponentError] when sevgi/geometry is unavailable
+        def Hatch(element, angle:, step:, initial: nil, **kwargs)
+          begin
+            require "sevgi/geometry"
+
+          rescue ::LoadError => e
+            raise unless e.path == "sevgi/geometry"
+
+            MissingComponentError.("sevgi/geometry")
+          end
+
+          Draw(Geometry::Operation.sweep!(element, initial: initial || element.position, angle:, step:), **kwargs)
         end
       end
     end

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

@@ -3,10 +3,22 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for collecting and hiding SVG ids.
       module Identify
+        # Index of element ids under a subtree.
         class Identifiers
-          attr_reader :element, :namespace, :collision
+          # @return [Sevgi::Graphics::Element] indexed root element
+          attr_reader :element
 
+          # @return [Hash<String, Sevgi::Graphics::Element>] id namespace
+          attr_reader :namespace
+
+          # @return [Hash<String, Array<Sevgi::Graphics::Element>>] duplicate id groups
+          attr_reader :collision
+
+          # Builds an id index for an element subtree.
+          # @param element [Sevgi::Graphics::Element] root element
+          # @return [void]
           def initialize(element)
             @element = element
             @namespace = {}
@@ -15,10 +27,16 @@ module Sevgi
             build
           end
 
+          # Reports whether duplicate ids were found.
+          # @return [Boolean]
           def conflict?
             !@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
@@ -38,6 +56,8 @@ module Sevgi
           end
         end
 
+        # Moves visible id attributes to Sevgi-internal id storage.
+        # @return [Sevgi::Graphics::Element] self
         def Disidentify
           Traverse do |element|
             next unless element[:id]
@@ -46,6 +66,8 @@ module Sevgi
           end
         end
 
+        # Builds an id index for this element subtree.
+        # @return [Sevgi::Graphics::Mixtures::Identify::Identifiers]
         def Identifiers = Identifiers.new(self)
       end
     end

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

@@ -3,14 +3,41 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for including derendered SVG/XML fragments.
       module Include
         require "sevgi/derender"
 
+        # Includes a derendered node matching an id.
+        # @param file [String] source SVG/XML file
+        # @param id [String, Symbol] source node id
+        # @return [Sevgi::Graphics::Element] included element
+        # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
         def Include(file, id) = Derender.evaluate_file(file, self, id:)
-        def Include!(file, id) = Derender.evaluate_file!(file, self, id:)
-      rescue ::LoadError
-        def Include(...) = raise NoMethodError, "\"sevgi/derender\" required"
-        def Include!(...) = raise NoMethodError, "\"sevgi/derender\" required"
+
+        # Includes the children of a derendered node matching an id.
+        # @param file [String] source SVG/XML file
+        # @param id [String, Symbol] source node id
+        # @return [Array<Sevgi::Graphics::Element>] included children
+        # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
+        def IncludeChildren(file, id) = Derender.evaluate_file!(file, self, id:)
+      rescue ::LoadError => e
+        raise unless e.path == "sevgi/derender"
+
+        # @overload IncludeChildren(file, id)
+        #   Raises because sevgi/derender is unavailable.
+        #   @param file [String] source SVG/XML file
+        #   @param id [String, Symbol] source node id
+        #   @return [void]
+        #   @raise [Sevgi::MissingComponentError] always
+        def IncludeChildren(...) = MissingComponentError.("sevgi/derender")
+
+        # @overload Include(file, id)
+        #   Raises because sevgi/derender is unavailable.
+        #   @param file [String] source SVG/XML file
+        #   @param id [String, Symbol] source node id
+        #   @return [void]
+        #   @raise [Sevgi::MissingComponentError] always
+        def Include(...) = MissingComponentError.("sevgi/derender")
       end
     end
   end

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

@@ -3,7 +3,15 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # Inkscape-specific SVG DSL helpers.
       module Inkscape
+        # Adds Inkscape template metadata.
+        # @param name [String] template name
+        # @param desc [String, nil] short description
+        # @param author [String, nil] author
+        # @param date [String, nil] date
+        # @param keywords [Array<String>, String, nil] keywords
+        # @return [Sevgi::Graphics::Element] template metadata element
         def InkscapeTemplateInfo(name:, desc: nil, author: nil, date: nil, keywords: nil)
           Element(:"inkscape:_templateinfo") do
             Element(:"inkscape:_name", name)
@@ -14,29 +22,59 @@ module Sevgi
           end
         end
 
+        # Renders a callable module inside a group.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] group attributes
+        # @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) }
         end
 
+        # Renders a callable module inside an Inkscape layer.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] layer attributes
+        # @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) }
         end
 
+        # Renders a callable module inside an insensitive Inkscape layer.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] layer attributes
+        # @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) }
         end
 
+        # @overload layer(**attributes)
+        #   Builds an Inkscape layer group.
+        #   @param attributes [Hash] layer attributes
+        #   @return [Sevgi::Graphics::Element] layer group
         def layer(**, &block)
           g("inkscape:groupmode": "layer", **, &block)
         end
 
+        # @overload layer!(**attributes)
+        #   Builds an insensitive Inkscape layer group.
+        #   @param attributes [Hash] layer attributes
+        #   @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|
@@ -48,12 +86,20 @@ module Sevgi
           end
         end
 
+        # Builds a tabular set of Inkscape pages.
+        # @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 * (height + gap), row * (width + gap), "#{row + 1}x#{col + 1}")
+                  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
@@ -62,6 +108,10 @@ module Sevgi
         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
+        #   @return [Sevgi::Graphics::Element] symbol group
         def symbol!(**, &block)
           if Is?(:defs)
             g(role: "inkscape:symbol", **, &block)
@@ -70,10 +120,6 @@ module Sevgi
           end
         end
 
-        def Symbol!(mod, *args, **kwargs, &block)
-          kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
-          symbol!(**kwargs) { Call(mod, *args, &block) }
-        end
       end
     end
   end

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

@@ -2,17 +2,29 @@
 
 module Sevgi
   module Graphics
+    # Raised when graphics lint checks fail.
     LintError = Class.new(Error)
 
     module Mixtures
+      # DSL helpers for pre-render structural linting.
       module Lint
+        # @overload Lint
+        #   Runs graphics lint checks.
+        #   @return [true]
+        #   @raise [Sevgi::Graphics::LintError] when a lint check fails
         def Lint(...)
           IdentitiesAreUniq.(self, ...)
         end
 
+        # Lint check that rejects duplicate visible ids.
+        # @api private
         module IdentitiesAreUniq
           extend self
 
+          # Checks an element subtree for duplicate ids.
+          # @param element [Sevgi::Graphics::Element] root element
+          # @return [true]
+          # @raise [Sevgi::Graphics::LintError] when duplicate ids exist
           def call(element)
             return true unless (identifiers = element.Identifiers()).conflict?
 

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

@@ -3,9 +3,20 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # Compatibility helpers for profiles that do not load richer mixtures.
       module Polyfills
+        # @overload layer(*args, **attributes)
+        #   Builds a generic group as a layer fallback.
+        #   @param args [Array<Object>] group content arguments
+        #   @param attributes [Hash] group attributes
+        #   @return [Sevgi::Graphics::Element] group element
         def layer(...) = g(...)
 
+        # @overload symbol!(*args, **attributes)
+        #   Builds a regular symbol as a fallback for hidden symbols.
+        #   @param args [Array<Object>] symbol content arguments
+        #   @param attributes [Hash] symbol attributes
+        #   @return [Sevgi::Graphics::Element] symbol element
         def symbol!(...) = symbol(...)
       end
     end