sevgi-sundries 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d304fd508f93b48a0e255d7e87d5e7477ed8a4ba5f132af7e0644c5b70055fa9
-  data.tar.gz: bddf4a00ae89d3f726cd1961815c89da921157f43eff7d57eaca13c5da25e049
+  metadata.gz: e8ddc5568e2938adbef615c7bc12663083287016955cd708bd342ec95423bfea
+  data.tar.gz: 64b06db206dcf954131c8348e0e1871a39c80677f83a15fc683cc84ab943d2aa
 SHA512:
-  metadata.gz: 5ef78b3c182dae1ff9c45659e7b1c94d0b7e29f36ed52d092b5d05c779f8e9ccf51c302e354131ccfc5f379d85e6e611beed1b8639a34ad1897fcb6f2b32a66d
-  data.tar.gz: d8ca3086912c399b09d25fb2b65fd30ad1782d77caa586148de52d20ff3029898c01eba42f7834e8531a0c7e575a8fcf7ddba05a6a5c3c762509870792d183de
+  metadata.gz: de63cbabb66ebaa15dfbb78d4aa5cb14384fb8414c15cd13f4a5e1665c3e8a28d66bfef4e7014acb51c486024efcc1e545f04d10172b228716e27050ac1854ff
+  data.tar.gz: 9b74f16efebe20b184b0ba277d588e20403cb3633256868b03b8d9bcf608f846bb266283283bbf7316e65fb0de5c065d69e20ab3f5fd5c7c597ecf74b0f1bc57

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Sevgi Sundries follows the root Sevgi release notes:
+https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Sundries is distributed under the GNU General Public License v3.0 or later.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+Full project license: https://github.com/roktas/sevgi/blob/main/LICENSE

data/README.md

@@ -0,0 +1,55 @@
+# Sevgi Sundries
+
+Helper objects and export tools for Sevgi drawings.
+
+## Install
+
+```sh
+gem install sevgi-sundries
+```
+
+## Require
+
+```ruby
+require "sevgi/sundries"
+```
+
+## Example
+
+```ruby
+rect = Sevgi::Geometry::Rect[3, 5]
+tile = Sevgi::Sundries::Tile.new(rect)
+tile.box.height
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+Basic ruler, grid, and tile helpers need only Ruby dependencies. Installing `sevgi-sundries` does not install native
+export gems.
+
+PDF/PNG export helpers load the optional Ruby gems `cairo`, `rsvg2`, and `hexapdf` only when export is used. Install
+their system libraries and gems separately:
+
+```sh
+sudo apt-get update
+sudo apt-get install -y libcairo2-dev libgdk-pixbuf-2.0-dev libgirepository1.0-dev libglib2.0-dev librsvg2-dev pkg-config
+gem install cairo rsvg2 hexapdf
+```
+
+On macOS with Homebrew:
+
+```sh
+brew install cairo gdk-pixbuf gobject-introspection librsvg pkg-config
+gem install cairo rsvg2 hexapdf
+```
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-sundries
+- Source: https://github.com/roktas/sevgi/tree/main/sundries
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/sundries/export/native.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../export"
+
 require "cairo"
 require "fileutils"
 require "hexapdf"
@@ -9,31 +11,51 @@ require "tempfile"
 module Sevgi
   module Sundries
     module Export
-      ExportError = Class.new(Error)
-
-      DEFAULT_DPI = 96.0
-
-      def self.call(svg, output, format: nil, width: nil, height: nil, dpi: DEFAULT_DPI, css: nil, &block)
+      %i[
+        call
+        stamp
+        stamp!
+      ].each { remove_method(it) if method_defined?(it) }
+
+      # Exports SVG source to a PDF or PNG file using librsvg and Cairo.
+      # @param svg [String] SVG source content
+      # @param output [String, #to_s] output file path
+      # @param format [Symbol, String, nil] explicit output format, or nil to infer from output extension
+      # @param width [Numeric, nil] target width in output pixels for PNG, or CSS pixels before PDF point conversion
+      # @param height [Numeric, nil] target height in output pixels for PNG, or CSS pixels before PDF point conversion
+      # @param dpi [Numeric] CSS pixel density used for absolute SVG units and PDF point conversion
+      # @param css [String, nil] CSS inserted before the closing svg tag before rendering
+      # @yield [svg] optional source transformation applied before rendering
+      # @yieldparam svg [String] SVG source after optional CSS injection
+      # @yieldreturn [String] SVG source to render
+      # @return [Object] the original output argument
+      # @raise [Sevgi::ArgumentError] when SVG content is not a string or output is blank
+      # @raise [Sevgi::Sundries::Export::ExportError] when format, SVG parsing, SVG dimensions, or render dimensions are invalid
+      def call(svg, output, format: nil, width: nil, height: nil, dpi: DEFAULT_DPI, css: nil, &block)
         ArgumentError.("SVG content must be a String") unless svg.is_a?(String)
         ArgumentError.("Export output must be provided") if output.nil? || output.to_s.strip.empty?
 
         svg = inject(svg, css) if css && !css.strip.empty?
         svg = block.call(svg) if block
+        ArgumentError.("SVG content must be a String") unless svg.is_a?(String)
 
-        renderer = Renderer.method(format_for!(format, output))
-        handle = Rsvg::Handle.new_from_data(svg)
+        format = format_for!(format, output)
+        renderer = Renderer.method(format)
 
-        iw, ih = intrinsic_size(handle)
-        ExportError.("Invalid SVG dimensions") if iw <= 0 || ih <= 0
+        begin
+          handle = Rsvg::Handle.new_from_data(svg)
 
-        scale = dpi / DEFAULT_DPI
+          iw, ih = intrinsic_size(handle)
+          ExportError.("Invalid SVG dimensions") if iw <= 0 || ih <= 0
 
-        iw *= scale
-        ih *= scale
+          scale = dpi / DEFAULT_DPI
 
-        tw, th = target_size(iw, ih, width, height)
+          iw *= scale
+          ih *= scale
+
+          tw, th = target_size(iw, ih, width, height)
+          ExportError.("Invalid export dimensions") unless target_size?(format, tw, th)
 
-        begin
           renderer.call(
             handle: handle,
             output: output.to_s,
@@ -50,56 +72,49 @@ module Sevgi
         output
       end
 
-      AVAILABLE = (EXTENSIONS = {
-        ".pdf" => :pdf,
-        ".png" => :png
-      }.freeze)
-        .invert
-        .freeze
-
-      def format_for!(format, output)
-        if format
-          format = format.to_sym
-          ExportError.("Unsupported export format: #{format}") unless AVAILABLE.key?(format)
-
-          format
-        else
-          ext = File.extname(output.to_s).downcase
-          ExportError.("Unrecognized file extension: #{ext}") unless EXTENSIONS.key?(ext)
-
-          EXTENSIONS[ext]
-        end
-      end
-
-      def inject(svg, css) = svg.sub("</svg>", "<style>#{css}</style></svg>")
-
+      # Replaces exact placeholder text objects in PDF streams.
+      # The placeholder must appear as a PDF literal string in a white text object matching the export stamp pattern.
+      # Replacement text is escaped as a PDF literal string. When no exact match is replaced, the output file is not
+      # written.
+      # @param infile [String] source PDF file path
+      # @param outfile [String] destination PDF file path
+      # @param stamp [String] replacement text
+      # @param placeholder [String] placeholder text to replace
+      # @return [Boolean] true when at least one matching placeholder was replaced
+      # @raise [Sevgi::Sundries::Export::ExportError] when the PDF cannot be read, rewritten, or stamped
       def stamp(infile, outfile, stamp:, placeholder:)
         doc = HexaPDF::Document.open(infile)
-        stamped = false
+        replacements = 0
 
         doc.pages.each do |page|
           Array(page[:Contents]).each do |ref|
             obj = doc.object(ref)
             next unless obj.respond_to?(:stream)
 
-            data = obj.stream
-            next unless data.include?("(#{placeholder})")
+            data, count = stamp_stream(obj.stream, stamp:, placeholder:)
+            next if count.zero?
 
-            data = data.gsub(
-              %r{1 1 1 rg (BT\s+.*?/\S+ \d+ Tf\s+)\(#{Regexp.escape(placeholder)}\)Tj}m,
-              "0.101961 0.101961 0.101961 rg \\1(#{stamp})Tj"
-            )
+            replacements += count
 
             obj.stream = data
             obj.set_filter(:FlateDecode)
-            stamped = true
           end
         end
 
-        doc.write(outfile, optimize: true) if stamped
-        stamped
+        doc.write(outfile, optimize: true) if replacements.positive?
+        replacements.positive?
+      rescue HexaPDF::Error, ::SystemCallError => e
+        ExportError.("PDF stamp error: #{e.message}")
       end
 
+      # Replaces exact placeholder text objects inside a PDF file in place.
+      # The input file is replaced only after at least one exact placeholder match is rewritten into a non-empty output
+      # file.
+      # @param infile [String] PDF file path to modify
+      # @param stamp [String] replacement text
+      # @param placeholder [String] placeholder text to replace
+      # @return [Boolean] true when at least one matching placeholder was replaced
+      # @raise [Sevgi::Sundries::Export::ExportError] when the PDF cannot be read, rewritten, stamped, or replaced
       def stamp!(infile, stamp:, placeholder:)
         temp = Tempfile.new(%w[stamp .pdf], File.dirname(infile))
         stamped = stamp(infile, temp.path, stamp:, placeholder:)
@@ -112,6 +127,8 @@ module Sevgi
         end
 
         stamped
+      rescue ::SystemCallError => e
+        ExportError.("PDF stamp error: #{e.message}")
       ensure
         temp&.close!
       end
@@ -178,11 +195,52 @@ module Sevgi
             [iw, ih]
           end
         end
+
+        def target_size?(format, width, height)
+          return false if width <= 0 || height <= 0
+          return false unless width.finite? && height.finite?
+          return true unless format == :png
+
+          width.round.positive? && height.round.positive?
+        end
+
+        PDF_LITERAL_ESCAPE = {
+          "\\" => "\\\\",
+          "(" => "\\(",
+          ")" => "\\)",
+          "\b" => "\\b",
+          "\f" => "\\f",
+          "\n" => "\\n",
+          "\r" => "\\r",
+          "\t" => "\\t"
+        }.freeze
+
+        private_constant :PDF_LITERAL_ESCAPE
+
+        def pdf_literal(text)
+          "(#{text.to_s.each_char.map { PDF_LITERAL_ESCAPE.fetch(it, it) }.join})"
+        end
+
+        def stamp_stream(data, stamp:, placeholder:)
+          count = 0
+          pattern = %r{1 1 1 rg (BT\s+.*?/\S+ \d+ Tf\s+)#{Regexp.escape(pdf_literal(placeholder))}Tj}m
+          stamped = data.gsub(pattern) do
+            count += 1
+            "0.101961 0.101961 0.101961 rg #{Regexp.last_match(1)}#{pdf_literal(stamp)}Tj"
+          end
+
+          [stamped, count]
+        end
       end
 
+      # Low-level format renderers used by {Export.call}.
+      # @api private
       module Renderer
         extend self
 
+        # Returns a renderer method for a format.
+        # @param format [Symbol, String, nil] format name
+        # @return [Method, nil]
         def [](format)
           case format&.to_sym
           when :png
@@ -192,6 +250,15 @@ module Sevgi
           end
         end
 
+        # Renders SVG data to a PDF surface.
+        # @param handle [Rsvg::Handle] parsed SVG handle
+        # @param output [String] output file path
+        # @param tw [Numeric] target width in CSS pixels
+        # @param th [Numeric] target height in CSS pixels
+        # @param dpi [Numeric] CSS pixel density
+        # @return [void]
+        # @raise [Cairo::Error] when Cairo cannot write the PDF surface
+        # @raise [Rsvg::Error] when librsvg cannot render the document
         def pdf(handle:, output:, tw:, th:, dpi:, **)
           pw, ph = tw * (72.0 / dpi), th * (72.0 / dpi)
           surface = Cairo::PDFSurface.new(output, pw, ph)
@@ -202,6 +269,14 @@ module Sevgi
           surface.finish
         end
 
+        # Renders SVG data to a PNG image.
+        # @param handle [Rsvg::Handle] parsed SVG handle
+        # @param output [String] output file path
+        # @param tw [Numeric] target width in CSS pixels
+        # @param th [Numeric] target height in CSS pixels
+        # @return [void]
+        # @raise [Cairo::Error] when Cairo cannot write the PNG surface
+        # @raise [Rsvg::Error] when librsvg cannot render the document
         def png(handle:, output:, tw:, th:, **)
           surface = Cairo::ImageSurface.new(Cairo::FORMAT_ARGB32, tw.round, th.round)
           context = Cairo::Context.new(surface)

data/lib/sevgi/sundries/export/system.rb

@@ -6,18 +6,44 @@ require "tempfile"
 module Sevgi
   module Sundries
     module Export
-      # pdfcpu - https://pdfcpu.io/ (pdfcpu package)
-      def a5ona4(infile, outfile) = F.sh!("pdfcpu", "nup", "--", "form:A4L, border:off", outfile, "2", infile)
+      # Places a single A5 PDF page twice on an A4 landscape sheet with pdfcpu.
+      # @param infile [String] source PDF file path
+      # @param outfile [String] destination PDF file path
+      # @return [Sevgi::Function::Shell::Result] command result
+      # @raise [Sevgi::Error] when pdfcpu is missing or the command fails
+      # @raise [Errno::ENOENT] when the executable cannot be spawned
+      # @see https://pdfcpu.io/ pdfcpu
+      def a5_on_a4(infile, outfile) = F.sh!("pdfcpu", "nup", "--", "form:A4L, border:off", outfile, "2", infile)
 
-      def a5ona4!(infile)
+      # Replaces a PDF file with an A5-on-A4 layout generated by pdfcpu.
+      # @param infile [String] PDF file path to modify
+      # @return [void]
+      # @raise [Sevgi::Error] when pdfcpu is missing or the command fails
+      # @raise [Errno::ENOENT] when the executable cannot be spawned
+      def a5_on_a4!(infile)
         temp = Tempfile.new(%w[output .pdf], File.dirname(infile))
-        a5ona4(infile, temp.path)
+        a5_on_a4(infile, temp.path)
         FileUtils.mv(temp.path, infile)
       ensure
         temp&.close!
       end
 
-      # inkscape - https://inkscape.org/ (inkscape package)
+      # Exports an SVG file through Inkscape.
+      # @param infile [String] source SVG file path
+      # @param outfile [String, nil] output path, defaulting to infile with a .pdf extension
+      # @param format [Symbol, String, nil] explicit output format, or nil to infer from outfile
+      # @param background [String, nil] export background color
+      # @param opacity [Numeric, nil] export background opacity
+      # @param width [Numeric, nil] target export width
+      # @param height [Numeric, nil] target export height
+      # @param id [String, nil] SVG element id to export
+      # @param page [Integer, String, nil] page selector passed to Inkscape
+      # @param css [String, nil] CSS inserted before exporting
+      # @return [Sevgi::Function::Shell::Result] command result
+      # @raise [Sevgi::Sundries::Export::ExportError] when format or output extension is unsupported
+      # @raise [Sevgi::Error] when Inkscape is missing or the command fails
+      # @raise [Errno::ENOENT] when the executable cannot be spawned
+      # @see https://inkscape.org/ Inkscape
       def inkscape(
         infile,
         outfile = nil,
@@ -62,7 +88,20 @@ module Sevgi
         temp&.close!
       end
 
-      # rsvg-convert - https://gitlab.gnome.org/GNOME/librsvg (librsvg2-bin package)
+      # Exports an SVG file through rsvg-convert.
+      # @param infile [String] source SVG file path
+      # @param outfile [String, nil] output path, defaulting to infile with a .pdf extension
+      # @param format [Symbol, String, nil] explicit output format, or nil to infer from outfile
+      # @param background [String, nil] export background color
+      # @param width [Numeric, nil] target export width
+      # @param height [Numeric, nil] target export height
+      # @param id [String, nil] SVG element id to export
+      # @param css [String, nil] CSS inserted before exporting
+      # @return [Sevgi::Function::Shell::Result] command result
+      # @raise [Sevgi::Sundries::Export::ExportError] when format or output extension is unsupported
+      # @raise [Sevgi::Error] when rsvg-convert is missing or the command fails
+      # @raise [Errno::ENOENT] when the executable cannot be spawned
+      # @see https://gitlab.gnome.org/GNOME/librsvg librsvg
       def rsvg(
         infile,
         outfile = nil,
@@ -100,7 +139,13 @@ module Sevgi
         temp&.close!
       end
 
-      # pdfunite - https://poppler.freedesktop.org/ (poppler-utils package)
+      # Merges PDF files with pdfunite.
+      # @param sources [Array<String>] source PDF file paths
+      # @param outfile [String] destination PDF file path
+      # @return [Sevgi::Function::Shell::Result] command result
+      # @raise [Sevgi::Error] when pdfunite is missing or the command fails
+      # @raise [Errno::ENOENT] when the executable cannot be spawned
+      # @see https://poppler.freedesktop.org/ Poppler
       def unite(sources, outfile) = F.sh!("pdfunite", *sources, outfile)
 
       extend self

data/lib/sevgi/sundries/export.rb

@@ -1,4 +1,118 @@
 # frozen_string_literal: true
 
-require_relative "export/native"
+require "sevgi/function"
+
 require_relative "export/system"
+
+module Sevgi
+  module Sundries
+    # Exports SVG content and post-processes PDF output.
+    #
+    # Native PDF/PNG rendering is loaded lazily so installing `sevgi-sundries` for SVG-only helpers does not require the
+    # Cairo, RSVG, or HexaPDF gems. Native export entrypoints raise {Sevgi::MissingComponentError} when those optional
+    # gems are unavailable.
+    module Export
+      # Supported export format names mapped to file extensions.
+      AVAILABLE = (EXTENSIONS = {
+        ".pdf" => :pdf,
+        ".png" => :png
+      }.freeze)
+        .invert
+        .freeze
+
+      # Default SVG CSS pixel density.
+      DEFAULT_DPI = 96.0
+
+      # Raised when SVG export or PDF post-processing cannot be completed.
+      ExportError = Class.new(Error)
+
+      NATIVE_COMPONENTS = %w[
+        cairo
+        hexapdf
+        rsvg2
+      ].freeze
+
+      private_constant :NATIVE_COMPONENTS
+
+      # @overload call(svg, output, format: nil, width: nil, height: nil, dpi: DEFAULT_DPI, css: nil)
+      #   Exports SVG source to a PDF or PNG file using the optional native export gems.
+      #   @param svg [String] SVG source content
+      #   @param output [String, #to_s] output file path
+      #   @param format [Symbol, String, nil] explicit output format, or nil to infer from output extension
+      #   @param width [Numeric, nil] target width in output pixels for PNG, or CSS pixels before PDF point conversion
+      #   @param height [Numeric, nil] target height in output pixels for PNG, or CSS pixels before PDF point conversion
+      #   @param dpi [Numeric] CSS pixel density used for absolute SVG units and PDF point conversion
+      #   @param css [String, nil] CSS inserted before the closing svg tag before rendering
+      #   @yield [svg] optional source transformation applied before rendering
+      #   @yieldparam svg [String] SVG source after optional CSS injection
+      #   @yieldreturn [String] SVG source to render
+      #   @return [Object] the original output argument
+      #   @raise [Sevgi::ArgumentError] when SVG content is not a string or output is blank
+      #   @raise [Sevgi::MissingComponentError] when cairo, hexapdf, or rsvg2 is unavailable
+      #   @raise [Sevgi::Sundries::Export::ExportError] when format, SVG parsing, SVG dimensions, or render dimensions
+      #     are invalid
+      def call(*args, **kwargs, &block) = native!.call(*args, **kwargs, &block)
+
+      # Resolves the export format from an explicit value or output extension.
+      # @param format [Symbol, String, nil] explicit format
+      # @param output [String, #to_s] output path
+      # @return [Symbol] resolved format
+      # @raise [Sevgi::Sundries::Export::ExportError] when the explicit format or output extension is unsupported
+      def format_for!(format, output)
+        if format
+          format = format.to_sym
+          ExportError.("Unsupported export format: #{format}") unless AVAILABLE.key?(format)
+
+          format
+        else
+          ext = File.extname(output.to_s).downcase
+          ExportError.("Unrecognized file extension: #{ext}") unless EXTENSIONS.key?(ext)
+
+          EXTENSIONS[ext]
+        end
+      end
+
+      # Inserts CSS before the closing svg tag.
+      # @param svg [String] SVG source content
+      # @param css [String] CSS source content
+      # @return [String] SVG source with an added style element when a closing svg tag is present
+      # @raise [NoMethodError] when SVG content does not support string substitution
+      def inject(svg, css) = svg.sub("</svg>", "<style>#{css}</style></svg>")
+
+      # Replaces exact placeholder text objects in PDF streams.
+      # @param infile [String] source PDF file path
+      # @param outfile [String] destination PDF file path
+      # @param stamp [String] replacement text
+      # @param placeholder [String] placeholder text to replace
+      # @return [Boolean] true when at least one matching placeholder was replaced
+      # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
+      # @raise [Sevgi::Sundries::Export::ExportError] when the PDF cannot be read, rewritten, or stamped
+      def stamp(infile, outfile, stamp:, placeholder:) = native!.stamp(infile, outfile, stamp:, placeholder:)
+
+      # Replaces exact placeholder text objects inside a PDF file in place.
+      # @param infile [String] PDF file path to modify
+      # @param stamp [String] replacement text
+      # @param placeholder [String] placeholder text to replace
+      # @return [Boolean] true when at least one matching placeholder was replaced
+      # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
+      # @raise [Sevgi::Sundries::Export::ExportError] when the PDF cannot be read, rewritten, stamped, or replaced
+      def stamp!(infile, stamp:, placeholder:) = native!.stamp!(infile, stamp:, placeholder:)
+
+      extend self
+
+      class << self
+        private
+
+        def native!
+          require_relative "export/native"
+
+          self
+        rescue ::LoadError => e
+          raise unless NATIVE_COMPONENTS.include?(e.path)
+
+          MissingComponentError.(NATIVE_COMPONENTS.join(", "))
+        end
+      end
+    end
+  end
+end

data/lib/sevgi/sundries/grid.rb

@@ -4,11 +4,26 @@ require "delegate"
 
 module Sevgi
   module Sundries
+    # Builds a tile-like grid from horizontal and vertical rulers.
     class Grid < Tile
+      # Builds a grid using bracket syntax.
+      # @param x [Sevgi::Sundries::Ruler] horizontal ruler
+      # @param y [Sevgi::Sundries::Ruler] vertical ruler
+      # @return [Sevgi::Sundries::Grid]
+      # @raise [Sevgi::ArgumentError] when either argument is not a ruler
       def self.[](x, y) = new(x:, y:)
 
+      # @!attribute [r] x
+      #   @return [Sevgi::Sundries::Grid::X] horizontal axis ruler and line queries
+      # @!attribute [r] y
+      #   @return [Sevgi::Sundries::Grid::Y] vertical axis ruler and line queries
       attr_reader :x, :y
 
+      # Creates a grid from horizontal and vertical rulers.
+      # @param x [Sevgi::Sundries::Ruler] horizontal ruler
+      # @param y [Sevgi::Sundries::Ruler] vertical ruler
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when either argument is not a ruler
       def initialize(x:, y:)
         ArgumentError.("Arguments must be Ruler objects") unless [x, y].all?(Ruler)
 
@@ -18,6 +33,8 @@ module Sevgi
         super(Geometry::Rect[@x.u, @y.u], nx: @x.n, ny: @y.n)
       end
 
+      # Returns a graphics canvas matching the rulers and computed margins.
+      # @return [Sevgi::Graphics::Canvas]
       def canvas
         Graphics::Canvas.new(
           **Graphics::Paper[x.brut, y.brut].to_h,
@@ -25,13 +42,32 @@ module Sevgi
         )
       end
 
+      # Returns the fitted grid height.
+      # @return [Float]
       def height = y.d
 
+      # Returns the fitted grid width.
+      # @return [Float]
       def width = x.d
 
+      # Axis wrapper exposing grid line queries for one ruler direction.
       class Axis < DelegateClass(Ruler)
-        attr_reader :major, :halve, :minor
-
+        # Returns the major line query.
+        # @return [Sevgi::Sundries::Grid::Axis::Major]
+        attr_reader :major
+
+        # Returns the midpoint line query.
+        # @return [Sevgi::Sundries::Grid::Axis::Halve]
+        attr_reader :halve
+
+        # Returns the minor line query.
+        # @return [Sevgi::Sundries::Grid::Axis::Minor]
+        attr_reader :minor
+
+        # Creates an axis wrapper.
+        # @param this [Sevgi::Sundries::Ruler] ruler represented by this axis
+        # @param other [Sevgi::Sundries::Ruler] ruler used for perpendicular tick locations
+        # @return [void]
         def initialize(this, other)
           super(this)
 
@@ -40,13 +76,24 @@ module Sevgi
           @minor = Minor.new(self, other)
         end
 
+        # Memoized grid line query for an axis.
         class Query
+          # Creates a query.
+          # @param this [Sevgi::Sundries::Grid::Axis] axis receiving generated lines
+          # @param other [Sevgi::Sundries::Ruler] perpendicular ruler supplying tick distances
+          # @return [void]
           def initialize(this, other) = (@this, @other = this, other)
 
+          # Returns grid line endpoints as coordinate pairs.
+          # @return [Array<Array<Array<Float>>>]
           def xys = @xys ||= lines.map { it.points(true).map(&:deconstruct) }
 
+          # Returns grid line endpoints as points.
+          # @return [Array<Array<Sevgi::Geometry::Point>>]
           def points = @points ||= lines.map { it.points(true) }
 
+          # Returns generated grid lines.
+          # @return [Array<Sevgi::Geometry::Line>]
           def lines = @lines ||= lines!
 
           private
@@ -54,27 +101,56 @@ module Sevgi
           attr_reader :this, :other
         end
 
+        # Major grid line query.
         class Major < Query
-          def lines! = other.ds.map { this.line.shift(it) }
+          # Returns lines at major tick distances.
+          # @return [Array<Sevgi::Geometry::Line>]
+          def lines! = other.ds.map { this.line_at(it) }
         end
 
+        # Midpoint grid line query.
         class Halve < Query
-          def lines! = other.hs.map { this.line.shift(it) }
+          # Returns lines at midpoint tick distances.
+          # @return [Array<Sevgi::Geometry::Line>]
+          def lines! = other.hs.map { this.line_at(it) }
         end
 
+        # Minor grid line query.
         class Minor < Query
-          def lines! = other.ms.map { this.line.shift(it) }
+          # Returns lines at minor tick distances.
+          # @return [Array<Sevgi::Geometry::Line>]
+          def lines! = other.ms.map { this.line_at(it) }
         end
       end
 
+      # Horizontal grid axis.
       class X < Axis
+        # Returns the base horizontal line for this axis.
+        # @return [Sevgi::Geometry::Line]
         def line = @line ||= Geometry::Line[d, 0.0]
+
+        # Returns a horizontal line translated to a y coordinate.
+        # @param y [Numeric] y coordinate
+        # @return [Sevgi::Geometry::Line]
+        def line_at(y) = line.at([0.0, y])
       end
 
+      # Vertical grid axis.
       class Y < Axis
+        # Creates a vertical axis wrapper.
+        # @param this [Sevgi::Sundries::Ruler] horizontal ruler
+        # @param other [Sevgi::Sundries::Ruler] vertical ruler
+        # @return [void]
         def initialize(this, other) = super(other, this)
 
-        def line = @line || Geometry::Line[d, 90.0]
+        # Returns the base vertical line for this axis.
+        # @return [Sevgi::Geometry::Line]
+        def line = @line ||= Geometry::Line[d, 90.0]
+
+        # Returns a vertical line translated to an x coordinate.
+        # @param x [Numeric] x coordinate
+        # @return [Sevgi::Geometry::Line]
+        def line_at(x) = line.at([x, 0.0])
       end
     end
   end

data/lib/sevgi/sundries/ruler.rb

@@ -2,89 +2,236 @@
 
 module Sevgi
   module Sundries
+    # A one-dimensional interval divided into equal units.
     #
-    # <----------------------------------- d = n x u --------------------------------->
-    #
-    # <--------------h = d / 2 --------------->
-    #
-    # |---------+---------+---------+---------|---------+---------+---------+---------|
-    #
-    #           <--- u --->
+    # The compact reader names are part of the domain vocabulary:
+    # `u` is the unit length, `n` is the interval count, `d` is total
+    # distance, and `h` is the midpoint distance.
     #
+    # @example Interval geometry
+    #   # <---------------- d = n x u ---------------->
+    #   # |---------+---------+---------+---------|
+    #   #           <--- u --->
+    #   interval = Sevgi::Sundries::Interval[3, 4]
+    #   interval.d # => 12.0
     class Interval
+      # Builds an interval using bracket syntax.
+      # @param e [Numeric, #length] unit length or an object exposing length
+      # @param n [Integer] non-negative interval count
+      # @return [Sevgi::Sundries::Interval]
+      # @raise [Sevgi::ArgumentError] when count is not a non-negative integer
+      # @raise [Sevgi::ArgumentError] when the unit object does not expose length
+      # @raise [Sevgi::ArgumentError] when the measured unit length is not numeric
+      # @raise [Sevgi::ArgumentError] when the measured unit length is not finite
+      # @raise [Sevgi::ArgumentError] when the measured unit length is not positive
       def self.[](e, n) = new(e, n)
 
+      # @!attribute [r] n
+      #   @return [Integer] interval count
+      # @!attribute [r] u
+      #   @return [Float] unit length
       attr_reader :n, :u
 
-      def initialize(e, n) = (@u, @n = measure(e), n)
+      # Creates an interval.
+      # @param e [Numeric, #length] unit length or an object exposing length
+      # @param n [Integer] non-negative interval count
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when count is not a non-negative integer
+      # @raise [Sevgi::ArgumentError] when the unit object does not expose length
+      # @raise [Sevgi::ArgumentError] when the measured unit length is not numeric
+      # @raise [Sevgi::ArgumentError] when the measured unit length is not finite
+      # @raise [Sevgi::ArgumentError] when the measured unit length is not positive
+      def initialize(e, n)
+        @n = non_negative_integer(n, "Interval count")
+        @u = measure(e)
+      end
 
+      # Returns a major tick distance by index.
+      # @param i [Integer] tick index
+      # @return [Float, nil] distance from the interval origin, or nil when out of range
       def [](i) = ds[i]
 
-      def count(length) = (d / length.to_f).to_i
+      # Counts how many whole lengths fit into this interval.
+      # @param length [Numeric] candidate length
+      # @return [Integer]
+      # @raise [Sevgi::ArgumentError] when length is not numeric
+      # @raise [Sevgi::ArgumentError] when length is not finite
+      # @raise [Sevgi::ArgumentError] when length is not positive
+      def count(length) = (d / positive_number(length, "Interval count length")).to_i
 
+      # Returns the total interval distance.
+      # @return [Float]
       def d = @d ||= n * u
 
+      # Returns major tick distances, including both endpoints.
+      # @return [Array<Float>]
       def ds = @ds ||= Array.new(n + 1) { |i| i * u }
 
+      # Returns the midpoint distance.
+      # @return [Float]
       def h = @h ||= d / 2.0
 
+      # Returns midpoint tick distances for each interval segment.
+      # @return [Array<Float>]
       def hs = @hs ||= Array.new(n) { |i| u * (0.5 + i) }
 
+      # Returns the last major tick index.
+      # @return [Integer]
       def nds = @nds ||= ds.size - 1
 
+      # Returns the last midpoint tick index.
+      # @return [Integer]
       def nhs = @nhs ||= hs.size - 1
 
+      # @return [Float] total interval distance
       alias length d
 
       private
 
       def measure(e)
-        return e.to_f if e.is_a?(::Numeric)
+        value = if e.is_a?(::Numeric)
+          e
+        else
+          ArgumentError.("#{e.class}#length must be implemented") unless e.respond_to?(:length)
+
+          e.length
+        end
+
+        positive_number(value, "Interval unit length")
+      end
 
-        raise NoMethodError, "#{e.class}#length must be implemented" unless e.respond_to?(:length)
+      def non_negative_integer(value, field)
+        ArgumentError.("#{field} must be a non-negative Integer") unless value.is_a?(::Integer) && !value.negative?
 
-        e.length
+        value
+      end
+
+      def non_negative_number(value, field)
+        number = numeric(value, field)
+        ArgumentError.("#{field} must be non-negative") if number.negative?
+
+        number
+      end
+
+      def numeric(value, field)
+        ArgumentError.("#{field} must be Numeric") unless value.is_a?(::Numeric)
+
+        number = value.to_f
+        ArgumentError.("#{field} must be finite") unless number.finite?
+
+        number
+      end
+
+      def positive_integer(value, field)
+        ArgumentError.("#{field} must be a positive Integer") unless value.is_a?(::Integer) && value.positive?
+
+        value
+      end
+
+      def positive_number(value, field)
+        number = numeric(value, field)
+        ArgumentError.("#{field} must be positive") unless number.positive?
+
+        number
       end
     end
 
+    # Fits a repeated interval into a broader span with computed margins.
     #
-    # <------------------------ d = n x sd -----------------------------><--- waste = 2 x margin --->
-    # <----- u  = unit x multiple ----->
-    # <------ sd = su x sn        ----->                            (computed margin >= given margin)
-    #
-    # |----------+----------+----------|----------+----------+----------|···························|
-    #
-    # <----------------------------------------- brut ---------------------------------------------->
+    # A ruler stores both the fitted major interval and the source subinterval.
+    # The compact reader names mirror {Interval}: `brut` is the full available
+    # span, `sd/su/sn` describe the subinterval, and `waste` is distributed as
+    # equal margins.
     #
+    # @example Ruler geometry
+    #   # <--------- d = n x sd ---------><--- waste = 2 x margin --->
+    #   # <----- u = unit x multiple ----->
+    #   # <---------------- brut ---------------->
+    #   ruler = Sevgi::Sundries::Ruler.new(unit: 1, multiple: 10, brut: 150)
+    #   ruler.d # => 150.0
     class Ruler < Interval
+      # @!attribute [r] brut
+      #   @return [Float] full available span before fitting
+      # @!attribute [r] sub
+      #   @return [Sevgi::Sundries::Interval] source subinterval
       attr_reader :brut, :sub
 
+      # Creates a ruler fitted into the given span.
+      # @param brut [Numeric] full available span
+      # @param unit [Numeric] subinterval unit length
+      # @param multiple [Integer] number of subinterval units per major interval
+      # @param margin [Numeric] minimum margin on each side
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when brut is not numeric
+      # @raise [Sevgi::ArgumentError] when brut is not finite
+      # @raise [Sevgi::ArgumentError] when brut is negative
+      # @raise [Sevgi::ArgumentError] when unit is not numeric
+      # @raise [Sevgi::ArgumentError] when unit is not finite
+      # @raise [Sevgi::ArgumentError] when unit is not positive
+      # @raise [Sevgi::ArgumentError] when multiple is not a positive integer
+      # @raise [Sevgi::ArgumentError] when margin is not numeric
+      # @raise [Sevgi::ArgumentError] when margin is not finite
+      # @raise [Sevgi::ArgumentError] when margin is negative
+      # @raise [Sevgi::ArgumentError] when the fitting span is negative
       def initialize(brut:, unit:, multiple:, margin: 0.0)
-        super(@sub = Interval.new(unit, multiple), divide(unit:, multiple:, brut: (@brut = brut.to_f), margin:))
+        @brut = non_negative_number(brut, "Ruler brut")
+        unit = positive_number(unit, "Ruler unit")
+        multiple = positive_integer(multiple, "Ruler multiple")
+        margin = non_negative_number(margin, "Ruler margin")
+        @sub = Interval.new(unit, multiple)
+
+        n = divide(unit:, multiple:, brut: @brut, margin:)
+
+        ArgumentError.("Ruler fitting span must not be negative") if n.negative?
+
+        super(@sub, n)
       end
 
+      # Returns a ruler where the source subinterval is flattened into units.
+      # @return [Sevgi::Sundries::Ruler]
       def expand = self.class.new(unit: sub.u, multiple: 1, brut: d + waste, margin:)
 
+      # Returns the computed margin after fitting.
+      # @return [Float]
       def margin = @margin ||= waste / 2.0
 
+      # Returns minor tick distances across the fitted span.
+      # @return [Array<Float>]
       def ms = @ms ||= expand.ds
 
+      # Returns the unfitted distance distributed outside the fitted span.
+      # @return [Float]
       def waste = @waste ||= brut - d
 
+      # Returns the source subinterval count.
+      # @return [Integer]
       def sn = @sub.n
 
+      # Returns the source subinterval distance.
+      # @return [Float]
       def sd = @sub.d
 
+      # Returns the source subinterval unit length.
+      # @return [Float]
       def su = @sub.u
 
       protected
 
+      # Computes the number of major intervals fitting in the available span.
+      # @param unit [Numeric] subinterval unit length
+      # @param multiple [Integer] number of subinterval units per major interval
+      # @param brut [Numeric] full available span
+      # @param margin [Numeric] minimum margin on each side
+      # @return [Integer]
       def divide(unit:, multiple:, brut:, margin:) = F.count(brut - (2 * margin), unit * multiple)
     end
 
+    # Ruler variant that always chooses an even number of major intervals.
     class RulerEven < Ruler
       protected
 
+      # Computes an even number of major intervals fitting in the available span.
+      # @return [Integer]
       def divide(...) = (n = super).even? ? n : (n - 1)
     end
   end

data/lib/sevgi/sundries/tile.rb

@@ -2,47 +2,118 @@
 
 module Sevgi
   module Sundries
+    # Repeats a geometry element over a rectangular row and column layout.
     class Tile
       include Enumerable
 
+      # @!attribute [r] element
+      #   @return [Sevgi::Geometry::Element] source element repeated by the tile
+      # @!attribute [r] position
+      #   @return [Sevgi::Geometry::Point] tile origin
+      # @!attribute [r] nx
+      #   @return [Integer] number of columns
+      # @!attribute [r] ny
+      #   @return [Integer] number of rows
       attr_reader :element, :position, :nx, :ny
 
+      # Creates a tile from a source geometry element.
+      # @param element [Sevgi::Geometry::Element] geometry element to repeat
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] tile origin
+      # @param nx [Integer] number of columns
+      # @param ny [Integer] number of rows
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when element is not a geometry element
+      # @raise [Sevgi::ArgumentError] when nx or ny is not a positive integer
+      # @raise [Sevgi::ArgumentError] when position is not a point or two-number array
       def initialize(element, position: Geometry::Origin, nx: 1, ny: 1)
-        raise ArgumentError, "Must be an Element object: #{element}" unless element.is_a?(Geometry::Element)
+        ArgumentError.("Must be an Element object: #{element}") unless element.is_a?(Geometry::Element)
+        ArgumentError.("Tile nx must be positive") unless nx.is_a?(::Integer) && nx.positive?
+        ArgumentError.("Tile ny must be positive") unless ny.is_a?(::Integer) && ny.positive?
 
         @element = element
-        @position = position
+        @position = self.class.send(:position, position)
 
         @nx = nx
         @ny = ny
       end
 
+      # Returns a row by index.
+      # @param i [Integer] row index
+      # @return [Array<Sevgi::Geometry::Element>, nil]
       def [](i) = rows[i]
 
+      # Returns the bounding rectangle of the whole tile.
+      # @return [Sevgi::Geometry::Rect]
       def box = @box ||= Geometry::Rect[nx * element.box.width, ny * element.box.height, position:]
 
+      # Returns the first cell in the tile.
+      # @return [Sevgi::Geometry::Element]
       def cell = row.first
 
+      # Returns the bounding rectangle of a column.
+      # @param i [Integer] column index
+      # @return [Sevgi::Geometry::Rect]
       def colbox(i = 0) = Geometry::Rect[element.box.width, box.height, position: coordinate(0, i)]
 
+      # Returns cells grouped by column.
+      # @return [Array<Array<Sevgi::Geometry::Element>>]
       def cols = @cols ||= rows.transpose
 
+      # Returns a column by index.
+      # @param i [Integer] column index
+      # @return [Array<Sevgi::Geometry::Element>, nil]
       def col(i = 0) = cols[i]
 
+      # Iterates over rows.
+      # @yield [row] each row
+      # @yieldparam row [Array<Sevgi::Geometry::Element>] row cells
+      # @yieldreturn [void]
+      # @return [Enumerator, Array<Array<Sevgi::Geometry::Element>>] enumerator without a block, otherwise rows
       def each(...) = rows.each(...)
 
+      # Iterates over columns.
+      # @yield [column] each column
+      # @yieldparam column [Array<Sevgi::Geometry::Element>] column cells
+      # @yieldreturn [void]
+      # @return [Enumerator, Array<Array<Sevgi::Geometry::Element>>] enumerator without a block, otherwise columns
       def each_col(...) = cols.each(...)
 
+      # Returns a row by index.
+      # @param i [Integer] row index
+      # @return [Array<Sevgi::Geometry::Element>, nil]
       def row(i = 0) = rows[i]
 
+      # Returns the bounding rectangle of a row.
+      # @param i [Integer] row index
+      # @return [Sevgi::Geometry::Rect]
       def rowbox(i = 0) = Geometry::Rect[box.width, element.box.height, position: coordinate(i)]
 
+      # Returns cells grouped by row.
+      # @return [Array<Array<Sevgi::Geometry::Element>>]
       def rows = @rows ||= (0...ny).map { |i| (0...nx).map { |j| element.at(coordinate(i, j)) } }
 
+      # Iterates over rows.
+      # @return [Enumerator, Array<Array<Sevgi::Geometry::Element>>] enumerator without a block, otherwise rows
       alias each_row each
 
       private
 
+      # Coerces a public tile position.
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] tile origin
+      # @return [Sevgi::Geometry::Point]
+      # @raise [Sevgi::ArgumentError] when position is not a point or two-number array
+      def self.position(position)
+        return position if position.is_a?(Geometry::Point)
+
+        unless position.is_a?(::Array) && position.size == 2 && position.all?(::Numeric)
+          ArgumentError.("Tile position must be a Point or two-number Array")
+        end
+
+        Geometry::Point[*position]
+      end
+
+      private_class_method :position
+
       def coordinate(i, j = 0) = position.translate(j * element.box.width, i * element.box.height)
     end
   end

data/lib/sevgi/sundries/version.rb

@@ -2,6 +2,7 @@
 
 module Sevgi
   module Sundries
-    VERSION = "0.73.2"
+    # Component version.
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/sundries.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "sevgi/function"
+require "sevgi/geometry"
+require "sevgi/graphics"
 
 require_relative "sundries/ruler"
 require_relative "sundries/tile"
@@ -9,3 +11,13 @@ require_relative "sundries/grid"
 require_relative "sundries/export"
 
 require_relative "sundries/version"
+
+module Sevgi
+  # Layout, tiling, grid, and export helpers shared by Sevgi consumers.
+  #
+  # This component loads its eager public surfaces directly. `Ruler`, `Tile`, and `Grid` therefore require
+  # `sevgi-function`, `sevgi-geometry`, and `sevgi-graphics` as runtime dependencies of the `sevgi-sundries` gem.
+  # Native PDF/PNG export gems are optional and loaded only by {Export} when export is used.
+  module Sundries
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-sundries
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,62 +15,50 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
 - !ruby/object:Gem::Dependency
-  name: cairo
+  name: sevgi-geometry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: hexapdf
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: 0.94.0
 - !ruby/object:Gem::Dependency
-  name: rsvg2
+  name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: 4.3.6
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: 4.3.6
+        version: 0.94.0
 description: Enhances the Sevgi toolkit with helper objects.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sevgi/sundries.rb
 - lib/sevgi/sundries/export.rb
@@ -95,7 +83,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0.pre.preview1
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="