sevgi-sundries 0.73.2 → 0.93.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d304fd508f93b48a0e255d7e87d5e7477ed8a4ba5f132af7e0644c5b70055fa9
-  data.tar.gz: bddf4a00ae89d3f726cd1961815c89da921157f43eff7d57eaca13c5da25e049
+  metadata.gz: 6094018249be152bff171c6077c6b5f7c9bd9f0d24c68381afbe05674e121da0
+  data.tar.gz: 8b9a02a83b2fd4b3614b65fed7c7922b611b78790e187167db3361cdd301cdeb
 SHA512:
-  metadata.gz: 5ef78b3c182dae1ff9c45659e7b1c94d0b7e29f36ed52d092b5d05c779f8e9ccf51c302e354131ccfc5f379d85e6e611beed1b8639a34ad1897fcb6f2b32a66d
-  data.tar.gz: d8ca3086912c399b09d25fb2b65fd30ad1782d77caa586148de52d20ff3029898c01eba42f7834e8531a0c7e575a8fcf7ddba05a6a5c3c762509870792d183de
+  metadata.gz: ea257e8c2b131b3ae278d35d14850391f6a4bf33467a528d87aa5ec0cd8dd3c4109376da978a3fdd4352d230f5c668d268914e390f33be4c1d28a775d5eabee9
+  data.tar.gz: 7ba89c1d630142ac180bc64aaa15564bb2d54b5a5e68daa1cd2a814f546cef6c1b76d08ff8504f64e4d0a9880c505577ca958c9ae96ce3e814fb584035593879

data/README.md

@@ -0,0 +1,5 @@
+# Sevgi Sundries
+
+Provides helper objects and export tools for Sevgi drawings.
+
+See the root [README](../README.md) and the documentation site for usage.

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

@@ -8,32 +8,53 @@ require "tempfile"
 
 module Sevgi
   module Sundries
+    # Exports SVG content and post-processes PDF output.
     module Export
+      # Raised when SVG export or PDF post-processing cannot be completed.
       ExportError = Class.new(Error)
 
+      # Default SVG CSS pixel density.
       DEFAULT_DPI = 96.0
 
+      # 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 self.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)
+
+        format = format_for!(format, output)
+        renderer = Renderer.method(format)
 
-        renderer = Renderer.method(format_for!(format, output))
-        handle = Rsvg::Handle.new_from_data(svg)
+        begin
+          handle = Rsvg::Handle.new_from_data(svg)
 
-        iw, ih = intrinsic_size(handle)
-        ExportError.("Invalid SVG dimensions") if iw <= 0 || ih <= 0
+          iw, ih = intrinsic_size(handle)
+          ExportError.("Invalid SVG dimensions") if iw <= 0 || ih <= 0
 
-        scale = dpi / DEFAULT_DPI
+          scale = dpi / DEFAULT_DPI
 
-        iw *= scale
-        ih *= scale
+          iw *= scale
+          ih *= scale
 
-        tw, th = target_size(iw, ih, width, height)
+          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,6 +71,7 @@ module Sevgi
         output
       end
 
+      # Supported export format names mapped to file extensions.
       AVAILABLE = (EXTENSIONS = {
         ".pdf" => :pdf,
         ".png" => :png
@@ -57,6 +79,11 @@ module Sevgi
         .invert
         .freeze
 
+      # 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
@@ -71,8 +98,19 @@ module Sevgi
         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
       def inject(svg, css) = svg.sub("</svg>", "<style>#{css}</style></svg>")
 
+      # Replaces a placeholder text object in a PDF stream.
+      # @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 a matching placeholder was replaced
+      # @raise [Sevgi::Sundries::Export::ExportError] when the PDF files cannot be read, written, or stamped
       def stamp(infile, outfile, stamp:, placeholder:)
         doc = HexaPDF::Document.open(infile)
         stamped = false
@@ -98,8 +136,16 @@ module Sevgi
 
         doc.write(outfile, optimize: true) if stamped
         stamped
+      rescue HexaPDF::Error, ::SystemCallError => e
+        ExportError.("PDF stamp error: #{e.message}")
       end
 
+      # Replaces a placeholder text object 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 a matching placeholder was replaced
+      # @raise [Sevgi::Sundries::Export::ExportError] when the PDF file cannot be read, written, 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 +158,8 @@ module Sevgi
         end
 
         stamped
+      rescue ::SystemCallError => e
+        ExportError.("PDF stamp error: #{e.message}")
       ensure
         temp&.close!
       end
@@ -178,11 +226,24 @@ 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
       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 +253,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 +272,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/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,33 @@ 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.
+      # @api private
       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 +77,25 @@ module Sevgi
           @minor = Minor.new(self, other)
         end
 
+        # Memoized grid line query for an axis.
+        # @api private
         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 +103,61 @@ module Sevgi
           attr_reader :this, :other
         end
 
+        # Major grid line query.
+        # @api private
         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.
+        # @api private
         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.
+        # @api private
         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.
+      # @api private
       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.
+      # @api private
       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,38 +2,81 @@
 
 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 length cannot be measured
       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 length cannot be measured
+      def initialize(e, n)
+        ArgumentError.("Interval count must be a non-negative Integer") unless n.is_a?(::Integer) && !n.negative?
+
+        @u = measure(e)
+        @n = n
+      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]
 
+      # Counts how many whole lengths fit into this interval.
+      # @param length [Numeric] candidate length
+      # @return [Integer]
       def count(length) = (d / length.to_f).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
@@ -41,50 +84,102 @@ module Sevgi
       def measure(e)
         return e.to_f if e.is_a?(::Numeric)
 
-        raise NoMethodError, "#{e.class}#length must be implemented" unless e.respond_to?(:length)
+        ArgumentError.("#{e.class}#length must be implemented") unless e.respond_to?(:length)
 
         e.length
       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 unit or multiple is not positive
+      # @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:))
+        ArgumentError.("Ruler unit must be positive") unless unit.to_f.positive?
+        ArgumentError.("Ruler multiple must be positive") unless multiple.to_f.positive?
+        ArgumentError.("Ruler margin must be non-negative") if margin.to_f.negative?
+
+        @brut = brut.to_f
+        margin = margin.to_f
+        @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,13 +2,32 @@
 
 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
       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
@@ -17,28 +36,63 @@ module Sevgi
         @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

data/lib/sevgi/sundries/version.rb

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

data/lib/sevgi/sundries.rb

@@ -9,3 +9,9 @@ require_relative "sundries/grid"
 require_relative "sundries/export"
 
 require_relative "sundries/version"
+
+module Sevgi
+  # Layout, tiling, grid, and export helpers shared by Sevgi consumers.
+  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.93.1
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
 - !ruby/object:Gem::Dependency
   name: cairo
   requirement: !ruby/object:Gem::Requirement