sevgi-geometry 0.95.0 → 0.98.2

data/lib/sevgi/geometry/operation.rb

@@ -2,7 +2,13 @@
 
 module Sevgi
   module Geometry
-    # Dispatches geometry operations to operation handler modules.
+    # Stateless operations that relate or derive geometry values.
+    #
+    # `alignment` returns a translation offset, while `align` applies that
+    # offset to a copy. Center alignment works on both axes; edge alignments
+    # change only the named axis and preserve the other coordinate. `sweep`
+    # derives boundary-to-boundary spans from a closed lined element, and
+    # `sweep!` additionally requires at least one span.
     module Operation
       extend self
 
@@ -15,24 +21,36 @@ module Sevgi
       # @!parse
       #   class << self
       #     # Returns an element translated to align with another element.
+      #     # Center alignment changes both axes. Edge alignments change only the named axis.
       #     # @param element [Sevgi::Geometry::Element] element to move
       #     # @param other [Sevgi::Geometry::Element] reference element
       #     # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
       #     # @return [Sevgi::Geometry::Element] translated element
       #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when an argument is not a geometry element
       #     # @raise [Sevgi::ArgumentError] when alignment is unknown
+      #     # @example Center one rectangle inside another
+      #     #   inner = Sevgi::Geometry::Rect[4, 2]
+      #     #   outer = Sevgi::Geometry::Rect[20, 10, position: [5, 5]]
+      #     #   Sevgi::Geometry::Operation.align(inner, outer).position.deconstruct # => [13.0, 9.0]
       #     def align(element, other, alignment = :center); end
       #
       #     # Returns the offset needed to align one element with another.
+      #     # Center alignment includes both axes. Edge alignments return zero on the other axis.
       #     # @param element [Sevgi::Geometry::Element] element to move
       #     # @param other [Sevgi::Geometry::Element] reference element
       #     # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
       #     # @return [Sevgi::Geometry::Point] translation offset
       #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when an argument is not a geometry element
       #     # @raise [Sevgi::ArgumentError] when alignment is unknown
+      #     # @example Calculate an offset without moving the element
+      #     #   inner = Sevgi::Geometry::Rect[4, 2]
+      #     #   outer = Sevgi::Geometry::Rect[20, 10, position: [5, 5]]
+      #     #   Sevgi::Geometry::Operation.alignment(inner, outer, :bottom).approx.deconstruct # => [0.0, 13.0]
       #     def alignment(element, other, alignment = :center); end
       #
       #     # Sweeps parallel lines across a lined element in both directions.
+      #     # `angle` is the direction of the returned lines; `step` is their signed perpendicular spacing.
+      #     # Open paths yield no interior spans.
       #     # @param element [Sevgi::Geometry::Element::Lined] element to intersect
       #     # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
       #     # @param angle [Numeric] clockwise sweep line angle in degrees
@@ -43,11 +61,17 @@ module Sevgi
       #     # @yieldreturn [void]
       #     # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
       #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
-      #     # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+      #     # @raise [Sevgi::Geometry::Error] when initial, angle, step, or limit is invalid
       #     # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
+      #     # @example Generate horizontal spans through a rectangle
+      #     #   rect = Sevgi::Geometry::Rect[10, 6]
+      #     #   lines = Sevgi::Geometry::Operation.sweep(rect, initial: [0, 0], angle: 0, step: 2)
+      #     #   lines.size                # => 4
+      #     #   lines.map(&:length).uniq # => [10.0]
       #     def sweep(element, initial:, angle:, step:, limit: Sweep::LIMIT); end
       #
       #     # Sweeps parallel lines across a lined element and requires at least one result.
+      #     # It has the same geometry as {sweep}, but raises when the result would be empty.
       #     # @param element [Sevgi::Geometry::Element::Lined] element to intersect
       #     # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
       #     # @param angle [Numeric] clockwise sweep line angle in degrees
@@ -58,19 +82,9 @@ module Sevgi
       #     # @yieldreturn [void]
       #     # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
       #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
-      #     # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+      #     # @raise [Sevgi::Geometry::Error] when initial, angle, step, or limit is invalid
       #     # @raise [Sevgi::Geometry::Operation::OperationError] when no lines are found or iteration reaches the limit
       #     def sweep!(element, initial:, angle:, step:, limit: Sweep::LIMIT); end
-      #
-      #     # Sweeps parallel lines in one signed direction from an equation.
-      #     # @param element [Sevgi::Geometry::Element::Lined] element to intersect
-      #     # @param equation [Sevgi::Geometry::Equation] initial sweep equation
-      #     # @param step [Numeric] signed distance between sweep lines
-      #     # @param limit [Integer] maximum iterations
-      #     # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
-      #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
-      #     # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
-      #     def unisweep(element, equation, step, limit: Sweep::LIMIT); end
       #   end
       # Registers one or more public operation methods.
       # @api private
@@ -87,7 +101,7 @@ module Sevgi
         define_singleton_method(operation) do |element, *args, **kwargs, &block|
           OperationInapplicableError.("Not a Geometric Element: #{element}") unless element.is_a?(Element)
           unless handler.applicable?(element)
-            OperationInapplicableError.("Unapplicable operation for #{element}: #{handler}")
+            OperationInapplicableError.("Operation not applicable to #{element}: #{handler}")
           end
 
           handler.public_send(operation, element, *args, **kwargs, &block)

data/lib/sevgi/geometry/point.rb

@@ -2,7 +2,8 @@
 
 module Sevgi
   module Geometry
-    # Affine transforms shared by immutable geometry tuples.
+    # Implementation owner and registry for public affine transformations on Point and lined elements.
+    # @api private
     module Affinity
       # Reflects a point across the selected axes.
       #
@@ -11,45 +12,141 @@ module Sevgi
       # @param x [Boolean] reflect across the x-axis
       # @param y [Boolean] reflect across the y-axis
       # @return [Sevgi::Geometry::Point]
-      def reflect(x: true, y: true) = with(x: (y ? -1 : 1) * self.x(), y: (x ? -1 : 1) * self.y())
+      # @raise [Sevgi::Geometry::Error] when a flag is not Boolean
+      def reflect(x: true, y: true)
+        Error.("Reflection x flag must be Boolean") unless x.equal?(true) || x.equal?(false)
+        Error.("Reflection y flag must be Boolean") unless y.equal?(true) || y.equal?(false)
+
+        with(x: (y ? -1 : 1) * self.x(), y: (x ? -1 : 1) * self.y())
+      end
 
       # Rotates a point around the origin using screen-space degrees.
       # @param a [Numeric] clockwise angle in degrees
       # @return [Sevgi::Geometry::Point]
-      def rotate(a) = with(x: (x * F.cos(a)) - (y * F.sin(a)), y: (x * F.sin(a)) + (y * F.cos(a)))
+      # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
+      def rotate(a)
+        a = Real[:angle, a]
+        with(x: (x * F.cos(a)) - (y * F.sin(a)), y: (x * F.sin(a)) + (y * F.cos(a)))
+      end
 
       # Scales a point from the origin.
       # @param sx [Numeric] x scale factor
       # @param sy [Numeric, Sevgi::Undefined] y scale factor, defaulting to sx
       # @return [Sevgi::Geometry::Point]
-      def scale(sx, sy = Undefined) = with(x: sx * x, y: Undefined.default(sy, sx) * y)
+      # @raise [Sevgi::Geometry::Error] when a scale is not a finite real number
+      def scale(sx, sy = Undefined)
+        sx = Real[:sx, sx]
+        sy = Real[:sy, Undefined.default(sy, sx)]
+        with(x: sx * x, y: sy * y)
+      end
 
       # Skews a point from the origin.
       # @param ax [Numeric] x-axis skew angle in degrees
       # @param ay [Numeric, Sevgi::Undefined] y-axis skew angle in degrees, defaulting to ax
       # @return [Sevgi::Geometry::Point]
-      def skew(ax, ay = Undefined) = with(x: x + (y * F.tan(ax)), y: y + (x * F.tan(Undefined.default(ay, ax))))
+      # @raise [Sevgi::Geometry::Error] when an angle is not a finite real number
+      def skew(ax, ay = Undefined)
+        ax = Real[:ax, ax]
+        ay = Real[:ay, Undefined.default(ay, ax)]
+        with(x: x + (y * F.tan(ax)), y: y + (x * F.tan(ay)))
+      end
 
       # Skews a point along x.
       # @param a [Numeric] skew angle in degrees
       # @return [Sevgi::Geometry::Point]
-      def skew_x(a) = with(x: x + (y * F.tan(a)))
+      # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
+      def skew_x(a) = with(x: x + (y * F.tan(Real[:angle, a])))
 
       # Skews a point along y.
       # @param a [Numeric] skew angle in degrees
       # @return [Sevgi::Geometry::Point]
-      def skew_y(a) = with(y: y + (x * F.tan(a)))
+      # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
+      def skew_y(a) = with(y: y + (x * F.tan(Real[:angle, a])))
 
       # Translates a point.
       # @param dx [Numeric] x offset
       # @param dy [Numeric, Sevgi::Undefined] y offset, defaulting to dx
       # @return [Sevgi::Geometry::Point]
-      def translate(dx, dy = Undefined) = with(x: x + dx, y: y + Undefined.default(dy, dx))
+      # @raise [Sevgi::Geometry::Error] when an offset is not a finite real number
+      def translate(dx, dy = Undefined)
+        dx = Real[:dx, dx]
+        dy = Real[:dy, Undefined.default(dy, dx)]
+        with(x: x + dx, y: y + dy)
+      end
     end
 
     # Immutable point in SVG/screen coordinates.
     #
-    # Use `Point[x, y]` to create a point from two coordinates.
+    # Use `Point[x, y]` to create a point from two coordinates. Public geometry
+    # methods that expect a point also accept `[x, y]`; explicit Point values are
+    # most useful when a result will be transformed, compared, or reused.
+    # @example Measure and rotate a point in screen coordinates
+    #   point = Sevgi::Geometry::Point[3, 4]
+    #   Sevgi::Geometry::Point.length(Sevgi::Geometry::Origin, point) # => 5.0
+    #   point.rotate(90).approx.deconstruct # => [-4.0, 3.0]
+    # @example Compare positions in screen coordinates
+    #   upper = Sevgi::Geometry::Point[4, 2]
+    #   lower = Sevgi::Geometry::Point[4, 8]
+    #   upper.above?(lower) # => true
+    #   upper.left?([6, 2]) # => true
+    # @see Sevgi::Geometry::Segment
+    # @!parse
+    #   class Point
+    #     # Creates a point from two coordinates.
+    #     # @param x [Numeric] x coordinate
+    #     # @param y [Numeric] y coordinate
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when a coordinate is not a finite Numeric
+    #     # @example Create a point with mathematical notation
+    #     #   Sevgi::Geometry::Point[3, 5]
+    #     def self.[](x, y); end
+    #
+    #     # Returns a point reflected across the selected axes.
+    #     # @param x [Boolean] reflect across the x-axis
+    #     # @param y [Boolean] reflect across the y-axis
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when a flag is not Boolean
+    #     def reflect(x: true, y: true); end
+    #
+    #     # Returns a point rotated around the origin.
+    #     # @param a [Numeric] clockwise angle in degrees
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
+    #     def rotate(a); end
+    #
+    #     # Returns a point scaled from the origin.
+    #     # @param sx [Numeric] x scale factor
+    #     # @param sy [Numeric, Sevgi::Undefined] y scale factor, defaulting to sx
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when a scale is not a finite real number
+    #     def scale(sx, sy = Undefined); end
+    #
+    #     # Returns a point skewed from the origin.
+    #     # @param ax [Numeric] x-axis skew angle in degrees
+    #     # @param ay [Numeric, Sevgi::Undefined] y-axis skew angle in degrees, defaulting to ax
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when an angle is not a finite real number
+    #     def skew(ax, ay = Undefined); end
+    #
+    #     # Returns a point skewed along x.
+    #     # @param a [Numeric] skew angle in degrees
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
+    #     def skew_x(a); end
+    #
+    #     # Returns a point skewed along y.
+    #     # @param a [Numeric] skew angle in degrees
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
+    #     def skew_y(a); end
+    #
+    #     # Returns a translated point.
+    #     # @param dx [Numeric] x offset
+    #     # @param dy [Numeric, Sevgi::Undefined] y offset, defaulting to dx
+    #     # @return [Sevgi::Geometry::Point]
+    #     # @raise [Sevgi::Geometry::Error] when an offset is not a finite real number
+    #     def translate(dx, dy = Undefined); end
+    #   end
     Point = Data.define(:x, :y) do
       include Comparable
       include Affinity
@@ -104,10 +201,13 @@ module Sevgi
       def initialize(x:, y:) = super(x: Real[:x, x], y: Real[:y, y])
 
       # Compares points by x, then y.
-      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
-      # @return [Integer, nil]
-      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
-      def <=>(other) = deconstruct <=> Tuple[Point, other].deconstruct
+      # @param other [Object] point or two-item coordinate array to compare
+      # @return [Integer, nil] comparison result, or nil when other is not a valid point value
+      def <=>(other)
+        deconstruct <=> Tuple[Point, other].deconstruct
+      rescue Error
+        nil
+      end
 
       # Reports whether this point is at or above another point in screen coordinates.
       # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
@@ -165,6 +265,8 @@ module Sevgi
       alias_method :==, :eql?
     end
 
+    private_constant :Affinity
+
     # Origin point in SVG/screen coordinates.
     Origin = Point.origin
   end

data/lib/sevgi/geometry/segment.rb

@@ -2,10 +2,31 @@
 
 module Sevgi
   module Geometry
-    # Immutable polar segment in SVG/screen coordinates.
+    # Immutable polar displacement in SVG/screen coordinates.
     #
-    # `length` is a distance and `angle` is a clockwise angle in degrees.
-    # Use `Segment[length, angle]` to create a segment from polar components.
+    # A Segment has no position: `length` is a distance and `angle` is a
+    # clockwise direction. Use {#ending} to apply it to a starting point or
+    # {#line} when a placed, finite line is required. `Segment[length, angle]`
+    # starts from polar components; `Segment.(starting, ending)` derives them
+    # from two points.
+    # @example Derive polar components from two points
+    #   segment = Sevgi::Geometry::Segment.([1, 2], [4, 6])
+    #   segment.length # => 5.0
+    #   segment.ending([1, 2]).deconstruct # => [4.0, 6.0]
+    # @example Use a cardinal direction
+    #   Sevgi::Geometry::Segment.upward(3).ending([5, 5]).deconstruct # => [5.0, 2.0]
+    # @see Sevgi::Geometry::Line
+    # @!parse
+    #   class Segment
+    #     # Creates a segment from polar components.
+    #     # @param length [Numeric] non-negative segment length
+    #     # @param angle [Numeric] clockwise angle in degrees
+    #     # @return [Sevgi::Geometry::Segment]
+    #     # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+    #     # @example Create a segment with mathematical notation
+    #     #   Sevgi::Geometry::Segment[5, 30]
+    #     def self.[](length, angle); end
+    #   end
     Segment = Data.define(:length, :angle) do
       include Comparable
 
@@ -56,9 +77,15 @@ module Sevgi
       def self.upward(length) = self[length, -90.0]
 
       class << self
-        # @return [Sevgi::Geometry::Segment]
+        # @overload horizontal(length)
+        #   Returns a rightward segment.
+        #   @param length [Numeric] segment length
+        #   @return [Sevgi::Geometry::Segment]
         alias_method :horizontal, :rightward
-        # @return [Sevgi::Geometry::Segment]
+        # @overload vertical(length)
+        #   Returns a downward segment.
+        #   @param length [Numeric] segment length
+        #   @return [Sevgi::Geometry::Segment]
         alias_method :vertical, :downward
       end
 
@@ -66,14 +93,22 @@ module Sevgi
       # @param length [Numeric] segment length
       # @param angle [Numeric] clockwise angle in degrees
       # @return [void]
-      # @raise [Sevgi::Geometry::Error] when a component is not a finite Numeric
-      def initialize(length:, angle:) = super(length: Real[:length, length], angle: Real[:angle, angle])
+      # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+      def initialize(length:, angle:)
+        length = Real[:length, length]
+        Error.("Segment length cannot be negative") if length.negative?
+
+        super(length:, angle: Real[:angle, angle])
+      end
 
       # Compares segments by length.
-      # @param other [Sevgi::Geometry::Segment, Array<Numeric>] segment to compare
-      # @return [Integer, nil]
-      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
-      def <=>(other) = length <=> Tuple[Segment, other].length
+      # @param other [Object] segment or two-item length/angle array to compare
+      # @return [Integer, nil] comparison result, or nil when other is not a valid segment value
+      def <=>(other)
+        length <=> Tuple[Segment, other].length
+      rescue Error
+        nil
+      end
 
       # Returns a segment rounded to precision.
       # @param precision [Integer, nil] decimal precision, or nil for the current function default
@@ -121,7 +156,35 @@ module Sevgi
       def y = length * F.sin(angle)
     end
 
-    # Lightweight polar value used where a plain length/angle tuple is enough.
-    Polar = Data.define(:length, :angle)
+    # Immutable length/angle constraint used when a full segment is not implied.
+    #
+    # @!attribute [r] length
+    #   @return [Float] non-negative target measure
+    # @!attribute [r] angle
+    #   @return [Float] direction used to derive a segment
+    # @!parse
+    #   class LengthAngle
+    #     # Creates a length-and-angle constraint.
+    #     # @param length [Numeric] finite non-negative target width or height
+    #     # @param angle [Numeric] finite direction in degrees
+    #     # @return [Sevgi::Geometry::LengthAngle]
+    #     # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+    #     # @example Create a constraint with mathematical notation
+    #     #   Sevgi::Geometry::LengthAngle[3, 90]
+    #     def self.[](length, angle); end
+    #   end
+    LengthAngle = Data.define(:length, :angle) do
+      # Creates a target-measure constraint.
+      # @param length [Numeric] finite non-negative target width or height
+      # @param angle [Numeric] finite direction in degrees
+      # @return [void]
+      # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+      def initialize(length:, angle:)
+        length = Real[:length, length]
+        Error.("LengthAngle length cannot be negative") if length.negative?
+
+        super(length:, angle: Real[:angle, angle])
+      end
+    end
   end
 end

data/lib/sevgi/geometry/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Geometry
     # Component version.
-    VERSION = "0.95.0"
+    VERSION = "0.98.2"
   end
 end

data/lib/sevgi/geometry.rb

@@ -14,10 +14,33 @@ require_relative "geometry/operation"
 require_relative "geometry/version"
 
 module Sevgi
-  # Screen-space geometry primitives used by Sevgi layout and drawing helpers.
+  # Immutable screen-space geometry values used by Sevgi layout and drawing helpers.
   #
   # Coordinates follow SVG screen conventions: +x points right, +y points down,
-  # and positive angles turn clockwise.
+  # and positive angles turn clockwise. Constructors accept Point and Segment
+  # objects or their two-number Array forms. Transformations return new values;
+  # they do not mutate their receiver.
+  #
+  # Shape constructors have two complementary notations: `Shape[...]` accepts
+  # dimensions or segments, while `Shape.(...)` accepts points. Named factories
+  # such as `Rect.from_size` and `Rect.from_corners` expose the same distinction
+  # when a call site benefits from spelling it out.
+  #
+  # Trigonometric construction can retain ordinary floating-point noise. Use
+  # `approx` for presentation values and `eq?` for precision-aware comparison;
+  # strict `==` intentionally compares the exact immutable value.
+  #
+  # @example Measure and move a line
+  #   line = Sevgi::Geometry::Line.([0, 0], [3, 4])
+  #   line.length                    #=> 5.0
+  #   line.translate(2, 1).starting #=> Point[2.0, 1.0]
+  # @example Follow SVG screen directions
+  #   origin = Sevgi::Geometry::Point.origin
+  #   Sevgi::Geometry::Point.angle(origin, [0, 10]) #=> 90.0
+  #   origin.translate(0, 10).below?(origin)        #=> true
+  # @see Sevgi::Geometry::Element::Lined
+  # @see Sevgi::Geometry::Operation
+  # @see https://sevgi.roktas.dev/geometry/ Geometry guide
   module Geometry
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-geometry
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 0.98.2
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,15 +15,15 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
-description: Enhances the Sevgi toolkit with geometry objects and methods.
+        version: 0.98.2
+description: Models the points, lines, shapes, and transforms used by the DSL.
 email: roktas@gmail.com
 executables: []
 extensions: []
@@ -73,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Tiny library for geometric computations.
+summary: Geometry values and operations for Sevgi drawings.
 test_files: []