sevgi-graphics 0.95.0 → 0.98.2

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

@@ -8,52 +8,96 @@ module Sevgi
       # DSL helpers for writing rendered SVG output.
       module Save
         # Default SVG extension.
+        # @api private
         EXT = ".svg"
 
+        private_constant :EXT
+
+        # Change-aware file writer with optional backup support.
+        # @api private
+        class Writer
+          # Writes content when it differs from the destination.
+          # @param path [String] expanded output path
+          # @param content [String] rendered content
+          # @param backup_suffix [String, nil] suffix used for an existing-file backup
+          # @yield [content] optionally normalizes old and new content for change detection
+          # @yieldparam content [String] old or new content
+          # @yieldreturn [String] normalized content
+          # @return [String, nil] expanded path when written, otherwise nil
+          # @raise [SystemCallError] when the destination or backup cannot be created, read, or written
+          def self.call(path, content, backup_suffix: nil, &filter)
+            output = "#{content.chomp}\n"
+
+            return unless F.changed?(path, output, &filter)
+
+            ::FileUtils.mkdir_p(::File.dirname(path))
+            if backup_suffix && !backup_suffix.empty? && ::File.exist?(path)
+              ::FileUtils.cp(path, "#{path}#{backup_suffix}")
+            end
+
+            path.tap { ::File.write(path, output) }
+          end
+        end
+
+        private_constant :Writer
+
         # Writes rendered SVG to standard output.
-        # @param kwargs [Hash] render options
-        # @yield [content] optionally transforms rendered content before output
-        # @yieldparam content [String] rendered SVG source
-        # @yieldreturn [String] transformed SVG source
-        # @return [Object] F.out return value
-        def Out(**kwargs, &filter)
-          F.out(self.(**kwargs), &filter)
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @return [nil]
+        # @raise [Sevgi::ArgumentError] when a render option or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @see Sevgi::Graphics::Document::Proto#call
+        def Out(**kwargs)
+          F.out(self.(**kwargs))
         end
 
-        # Saves rendered SVG to a path derived from the caller by default.
-        # @param path [String, nil] output path or directory
-        # @param default [String, nil] default output path
+        # Saves rendered SVG when its content differs from the destination.
+        # Relative destinations are expanded before being returned. When a non-empty backup suffix is given, an
+        # existing destination is copied immediately before replacement; unchanged saves leave both files untouched.
+        # Missing parent directories are created. An existing directory target uses the default file name.
+        # @example Save to a relative destination
+        #   path = Sevgi::Graphics.SVG(:minimal).Save("build/drawing.svg")
+        #   path == File.expand_path("build/drawing.svg") # => true
+        # @param path [String, #to_path, nil] output path or existing directory
+        # @param default [String, #to_path, nil] default output path
         # @param backup_suffix [String, nil] suffix used for an existing-file backup
-        # @yield [content] optionally transforms rendered content before output
-        # @yieldparam content [String] rendered SVG source
-        # @yieldreturn [String] transformed SVG source
-        # @return [Object] F.out return value
-        def Save(path = nil, default: nil, backup_suffix: nil, &filter)
-          default ||= F.subext(EXT, caller_locations(1..1).first.path)
-
-          if path
-            ::File.directory?(path) ? ::File.join(path, ::File.basename(default)) : path
-          else
-            default
-          end => path
-
-          ::FileUtils.mkdir_p(::File.dirname(path))
-          if backup_suffix && !backup_suffix.empty? && ::File.exist?(path)
-            ::FileUtils.cp(path, "#{path}#{backup_suffix}")
-          end
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @yield [content] optionally normalizes old and new content for change detection
+        # @yieldparam content [String] old or new SVG source
+        # @yieldreturn [String] normalized SVG source
+        # @return [String, nil] expanded path when written, or nil when unchanged
+        # @raise [Sevgi::ArgumentError] when a selected path/default, render option, or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @raise [SystemCallError] when the destination or backup cannot be created, read, or written
+        # @see Sevgi::Graphics::Document::Proto#call
+        def Save(path = nil, default: nil, backup_suffix: nil, **kwargs, &filter)
+          default = F.subext(EXT, caller_locations(1..1).first.path) if default.nil?
+          path = Path.resolve(path, default:, context: "Save")
 
-          Write(path, &filter)
+          Writer.(path, self.(**kwargs), backup_suffix:, &filter)
         end
 
         # Writes rendered SVG to a path.
-        # @param path [String] output path
-        # @param kwargs [Hash] render options
-        # @yield [content] optionally transforms rendered content before output
-        # @yieldparam content [String] rendered SVG source
-        # @yieldreturn [String] transformed SVG source
-        # @return [Object] F.out return value
+        # Missing parent directories are created. Unlike {#Save}, a directory is not treated as a request for a default
+        # file name.
+        # @param path [String, #to_path] output file path
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @yield [content] optionally normalizes old and new content for change detection
+        # @yieldparam content [String] old or new SVG source
+        # @yieldreturn [String] normalized SVG source
+        # @return [String, nil] expanded path when written, or nil when unchanged
+        # @raise [Sevgi::ArgumentError] when path, a render option, or an XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @raise [SystemCallError] when the destination cannot be read or written
+        # @see Sevgi::Graphics::Document::Proto#call
         def Write(path, **kwargs, &filter)
-          F.out(self.(**kwargs), path, &filter)
+          path = Path.(path, context: "Write path")
+          ArgumentError.("Write path must name a file") if ::File.directory?(path)
+
+          Writer.(path, self.(**kwargs), &filter)
         end
       end
     end

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

@@ -5,20 +5,89 @@ module Sevgi
     module Mixtures
       # DSL helpers for expanding callable modules into SVG symbols.
       module Symbols
-        # Renders module callables as symbols under defs.
-        # @param mod [Module] callable drawing module
+        # Builds one symbol set without adding helper methods to the document DSL.
+        # @api private
+        class Expansion
+          # Creates a symbol expansion.
+          # @param receiver [Sevgi::Graphics::Element] parent element
+          # @param mod [Module] module extended with {Sevgi::Graphics::Module}
+          # @return [void]
+          def initialize(receiver, mod)
+            @receiver = receiver
+            @mod = mod
+          end
+
+          # Builds a defs container and populates it from the callable module.
+          # @param args [Array<Object>] callable positional arguments
+          # @param attributes [Hash] defs attributes
+          # @param ids [#call, nil] symbol id mapper
+          # @param kwargs [Hash] callable keyword arguments
+          # @param block [Proc, nil] callable block argument
+          # @return [Sevgi::Graphics::Element] defs element
+          # @raise [Sevgi::ArgumentError] when an input channel is invalid
+          def call(*args, attributes:, ids:, **kwargs, &block)
+            methods = Graphics::Module.__send__(:callables, @mod)
+            ArgumentError.("Defs attributes must be a Hash") unless attributes.is_a?(::Hash)
+            ArgumentError.("Symbol ids must respond to call") if ids && !ids.respond_to?(:call)
+
+            defaults = @mod.name ? {id: F.demodulize(@mod.name).to_sym} : {}
+            attributes = Attribute.defaults(attributes, **defaults)
+            @args, @kwargs, @block = args, kwargs, block
+            @receiver.defs(**attributes).tap { populate(it, methods, ids) }
+          end
+
+          private
+
+          # Adds bases and symbols to a defs element.
+          # @param defs [Sevgi::Graphics::Element] defs element
+          # @param methods [Array<UnboundMethod>] callable methods
+          # @param ids [#call, nil] symbol id mapper
+          # @return [void]
+          def populate(defs, methods, ids)
+            context = Graphics::Module.__send__(:context, @mod, defs)
+            Graphics::Module.__send__(:bases, @mod).each { context.instance_exec(&it) }
+            methods.each { draw(defs, it, ids) }
+          end
+
+          # Adds one callable symbol.
+          # @param defs [Sevgi::Graphics::Element] defs element
+          # @param method [UnboundMethod] callable method
+          # @param ids [#call, nil] symbol id mapper
+          # @return [Object, nil] callable return value
+          def draw(defs, method, ids)
+            name = method.name
+            symbol = defs.symbol(id: ids ? ids.call(name) : name.to_s.tr("_", "-"))
+            symbol.title(name.to_s.split("_").map(&:capitalize).join(" "))
+            context = Graphics::Module.__send__(:context, @mod, symbol)
+            Graphics::Module.__send__(:invoke, context, symbol, [method], *@args, **@kwargs, &@block)
+          end
+        end
+
+        private_constant :Expansion
+
+        # Renders module callables as symbols under defs. Named modules default the defs 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] defs attributes
-        # @yield [name] converts each callable name to a symbol id
-        # @yieldparam name [Symbol] callable method name
-        # @yieldreturn [String, Symbol] symbol id
+        # Base blocks run once in the defs element before symbols are created. Positional arguments, keyword arguments,
+        # and the block are forwarded to each callable.
+        # @example Expand named drawing methods into reusable symbols
+        #   icons = Module.new do
+        #     extend Sevgi::Graphics::Module
+        #     def dot = circle r: 2
+        #     def tick = path d: "M 0 2 L 2 4 L 6 0"
+        #   end
+        #   Sevgi::Graphics.SVG(:minimal) { Symbols icons }
+        # @param attributes [Hash] defs attributes; String and Symbol names are normalized and must not collide
+        # @param ids [#call, nil] optional callable mapping each method name to a symbol id
+        # @param kwargs [Hash] callable keyword arguments
+        # @yield forwarded to each callable
+        # @yieldreturn [Object] callable-defined block result
         # @return [Sevgi::Graphics::Element] defs element
-        # @raise [Sevgi::ArgumentError] when mod is not a plain module
-        def Symbols(mod, *args, **kwargs, &block)
-          CallWithin(mod, :defs, :symbol, *args, **kwargs) do |name, element|
-            element[:id] = block ? block.call(name) : name.to_s.split("_").join("-")
-            title(name.to_s.split("_").map(&:capitalize).join(" "))
-          end
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module, attributes is not a Hash, or ids is
+        #   not callable
+        def Symbols(mod, *args, attributes: {}, ids: nil, **kwargs, &block)
+          Expansion.new(self, mod).call(*args, attributes:, ids:, **kwargs, &block)
         end
       end
     end

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

@@ -3,22 +3,35 @@
 module Sevgi
   module Graphics
     module Mixtures
-      # rubocop:disable Metrics/MethodLength
-      # DSL helpers for repeated SVG use elements.
+      # DSL helpers for defining one SVG template and repeating it through `use` elements.
+      #
+      # Use {Sevgi::Sundries::Tile} instead when Ruby code needs inspectable repeated geometry or row/column bounds
+      # rather than SVG references.
+      # @see Sevgi::Sundries::Tile
+      # @see https://sevgi.roktas.dev/sundries/#choose-a-layout-model Choosing a layout model
       module Tile
-        # Prefix used for generated tile CSS classes.
+        # Stable prefix used for generated tile CSS classes.
         PREFIX = "tile"
 
         # Builds a two-dimensional tile grid.
+        # Each use id has the form `id-row-column`, with one-based row and column numbers. Generated classes identify
+        # the one-based row and column and mark their first and last positions. A block defines the referenced template
+        # as a group under `defs` before the uses are added.
+        # @example Define and customize a tile grid
+        #   customize = proc { |use, x:, y:, nx:, ny:| use[:opacity] = (x + y + 1).fdiv(nx + ny) }
+        #   Sevgi::Graphics.SVG(:minimal) do
+        #     Tile("dot", nx: 2, dx: 10, ny: 2, dy: 10, proc: customize) { circle r: 2 }
+        #   end
         # @param id [String] referenced template id
         # @param nx [Integer] number of columns
-        # @param dx [Numeric] horizontal spacing
-        # @param ox [Numeric] horizontal offset
+        # @param dx [Numeric] finite horizontal spacing, normalized before coordinates are rendered
+        # @param ox [Numeric] finite horizontal offset, normalized before coordinates are rendered
         # @param ny [Integer] number of rows
-        # @param dy [Numeric] vertical spacing
-        # @param oy [Numeric] vertical offset
-        # @param proc [Proc, nil] optional coordinate/customization proc
-        # @yield evaluates the template drawing DSL in a generated group
+        # @param dy [Numeric] finite vertical spacing, normalized before coordinates are rendered
+        # @param oy [Numeric] finite vertical offset, normalized before coordinates are rendered
+        # @param proc [Proc, nil] optional callback invoked for each use as `(element, x:, y:, nx:, ny:)`, with
+        #   zero-based coordinates and total counts; the callback may mutate the element and its return value is ignored
+        # @yield evaluates the template drawing DSL in a generated `defs` group named by id
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
@@ -33,14 +46,9 @@ module Sevgi
           proc: nil,
           &block
         )
-          Helper.assert(id:, nx:, dx:, ox:, ny:, dy:, oy:, proc:)
-
-          href, coords = id, proc do |x, y|
-            # rubocop:disable Style/NestedTernaryOperator
-            # for pretty kwargs handling
-            x.zero? ? (y.zero? ? {} : {y:}) : (y.zero? ? {x:} : {x:, y:})
-            # rubocop:enable Style/NestedTernaryOperator
-          end
+          id, nx, dx, ox, ny, dy, oy, callback = Helper
+            .normalize(id:, nx:, dx:, ox:, ny:, dy:, oy:, proc:)
+            .values_at(:id, :nx, :dx, :ox, :ny, :dy, :oy, :proc)
 
           defs { g(id:, &block) } if block
 
@@ -52,34 +60,36 @@ module Sevgi
                 cs = Helper.classify(as: "col", index: x, upper: nx)
 
                 element = use(
-                  id: [href, y + 1, x + 1].join("-"),
-                  href: "##{href}",
+                  id: [id, y + 1, x + 1].join("-"),
+                  href: "##{id}",
                   class: [*rs, *cs].join(" "),
-                  **coords.((x * dx) + ox, (y * dy) + oy)
+                  **Helper.coordinates(
+                    x: Scalar.number((x * dx) + ox, context: "tile", field: :x),
+                    y: Scalar.number((y * dy) + oy, context: "tile", field: :y)
+                  )
                 )
-                proc&.call(element, x:, y:, nx:, ny:)
+                callback&.call(element, x:, y:, nx:, ny:)
               end
             end
           end
         end
 
         # Builds a one-dimensional horizontal tile row.
+        # Each use id has the form `id-column`, with a one-based column number. Generated classes identify the column and
+        # mark its first and last positions. A block defines the referenced template as a group under `defs` before the
+        # uses are added.
         # @param id [String] referenced template id
         # @param n [Integer] number of instances
-        # @param d [Numeric] horizontal spacing
-        # @param o [Numeric] horizontal offset
-        # @param proc [Proc, nil] optional coordinate/customization proc
-        # @yield evaluates the template drawing DSL in a generated group
+        # @param d [Numeric] finite horizontal spacing, normalized before coordinates are rendered
+        # @param o [Numeric] finite horizontal offset, normalized before coordinates are rendered
+        # @param proc [Proc, nil] optional callback invoked for each use as `(element, x:, n:)`, with a zero-based column
+        #   and total count; the callback may mutate the element and its return value is ignored
+        # @yield evaluates the template drawing DSL in a generated `defs` group named by id
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileX(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
-          Helper.assert(id:, n:, d:, o:, proc:)
-
-          href, coords = id, proc do |x|
-            # for pretty kwargs handling
-            x.zero? ? {} : {x:}
-          end
+          id, n, d, o, callback = Helper.normalize(id:, n:, d:, o:, proc:).values_at(:id, :n, :d, :o, :proc)
 
           defs { g(id:, &block) } if block
 
@@ -88,33 +98,32 @@ module Sevgi
               cs = Helper.classify(as: "col", index: x, upper: n)
 
               element = use(
-                id: [href, x + 1].join("-"),
-                href: "##{href}",
+                id: [id, x + 1].join("-"),
+                href: "##{id}",
                 class: cs.join(" "),
-                **coords.((x * d) + o)
+                **Helper.coordinates(x: Scalar.number((x * d) + o, context: "tile", field: :x))
               )
-              proc&.call(element, x:, n:)
+              callback&.call(element, x:, n:)
             end
           end
         end
 
         # Builds a one-dimensional vertical tile column.
+        # Each use id has the form `id-row`, with a one-based row number. Generated classes identify the row and mark its
+        # first and last positions. A block defines the referenced template as a group under `defs` before the uses are
+        # added.
         # @param id [String] referenced template id
         # @param n [Integer] number of instances
-        # @param d [Numeric] vertical spacing
-        # @param o [Numeric] vertical offset
-        # @param proc [Proc, nil] optional coordinate/customization proc
-        # @yield evaluates the template drawing DSL in a generated group
+        # @param d [Numeric] finite vertical spacing, normalized before coordinates are rendered
+        # @param o [Numeric] finite vertical offset, normalized before coordinates are rendered
+        # @param proc [Proc, nil] optional callback invoked for each use as `(element, y:, n:)`, with a zero-based row and
+        #   total count; the callback may mutate the element and its return value is ignored
+        # @yield evaluates the template drawing DSL in a generated `defs` group named by id
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileY(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
-          Helper.assert(id:, n:, d:, o:, proc:)
-
-          href, coords = id, proc do |y|
-            # for pretty kwargs handling
-            y.zero? ? {} : {y:}
-          end
+          id, n, d, o, callback = Helper.normalize(id:, n:, d:, o:, proc:).values_at(:id, :n, :d, :o, :proc)
 
           defs { g(id:, &block) } if block
 
@@ -123,12 +132,12 @@ module Sevgi
               rs = Helper.classify(as: "row", index: y, upper: n)
 
               element = use(
-                id: [href, y + 1].join("-"),
-                href: "##{href}",
+                id: [id, y + 1].join("-"),
+                href: "##{id}",
                 class: rs.join(" "),
-                **coords.((y * d) + o)
+                **Helper.coordinates(y: Scalar.number((y * d) + o, context: "tile", field: :y))
               )
-              proc&.call(element, y:, n:)
+              callback&.call(element, y:, n:)
             end
           end
         end
@@ -138,18 +147,14 @@ module Sevgi
         module Helper
           extend self
 
+          FINITE = %i[d dx dy o ox oy].freeze
+
           # Argument validators for tile helpers.
           ASSERTION = {
             id: proc { |name, value| "Argument '#{name}' must be a string" unless value.is_a?(::String) },
             n: proc { |name, value| positive_integer_issue(name, value) },
             nx: proc { |name, value| positive_integer_issue(name, value) },
             ny: proc { |name, value| positive_integer_issue(name, value) },
-            d: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
-            dx: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
-            dy: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
-            o: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
-            ox: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
-            oy: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
             proc: proc { |name, value| "Argument '#{name}' must be a proc" unless value.nil? || value.is_a?(::Proc) }
           }.freeze
 
@@ -161,22 +166,33 @@ module Sevgi
             "Argument '#{name}' must be a positive integer" unless value.is_a?(::Integer) && value.positive?
           end
 
-          # Validates tile arguments.
+          # Validates and normalizes tile arguments.
           # @param kwargs [Hash] tile arguments
-          # @return [nil]
+          # @return [Hash] independent arguments with spacing and offsets normalized to SVG numbers
           # @raise [Sevgi::ArgumentError] when an argument is missing or invalid
-          def assert(**kwargs)
-            kwargs.each do |name, value|
-              issue = "Argument '#{name}' required" if value == Undefined
+          def normalize(**kwargs)
+            kwargs.to_h do |name, value|
+              ArgumentError.("Argument '#{name}' required") if value == Undefined
+              [name, normalize_value(name, value)]
+            end
+          end
 
-              unless issue
-                next unless (assertion = ASSERTION[name])
-                next unless (issue = assertion.call(name, value))
-              end
+          def coordinates(**coordinates)
+            coordinates.reject { |_, value| value.zero? }
+          end
 
-              ArgumentError.(issue)
-            end
-            # rubocop:enable Metrics/MethodLength
+          def normalize_value(name, value)
+            return number(name, value) if FINITE.include?(name)
+            return value unless (assertion = ASSERTION[name])
+            return value unless (issue = assertion.call(name, value))
+
+            ArgumentError.(issue)
+          end
+
+          def number(name, value)
+            Scalar.number(value, context: "tile", field: name)
+          rescue ::Sevgi::ArgumentError
+            ArgumentError.("Argument '#{name}' must be a finite real number")
           end
 
           # Returns positional tile CSS classes.
@@ -191,6 +207,8 @@ module Sevgi
               classes << "#{PREFIX}-#{as}-last" if index + 1 == upper
             end
           end
+
+          private :normalize_value, :number
         end
 
         private_constant :Helper