sevgi-graphics 0.95.0 → 1.0.0

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

@@ -5,22 +5,84 @@ module Sevgi
     module Mixtures
       # DSL wrappers for common SVG shapes and content patterns.
       module Wrappers
+        # rubocop:disable Metrics/ParameterLists
+
+        # Builds an elliptical arc path ending at an absolute point.
+        # SVG resolves the ellipse from its endpoints, radii, and flags, including radius correction and zero radii.
+        # @example Draw an upper semicircle in screen coordinates
+        #   Sevgi::Graphics.SVG { ArcTo x1: 0, y1: 10, x2: 20, y2: 10, rx: 10, ry: 10, sweep: true }
+        # @param x2 [Numeric] finite ending x coordinate
+        # @param y2 [Numeric] finite ending y coordinate
+        # @param rx [Numeric] finite local x radius
+        # @param ry [Numeric] finite local y radius
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
+        # @param rotation [Numeric] clockwise ellipse rotation in degrees
+        # @param large [Boolean] select the arc exceeding a half turn
+        # @param sweep [Boolean] select increasing parameter angles
+        # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not finite real or a flag is not Boolean
+        def ArcTo(x2:, y2:, rx:, ry:, x1: 0, y1: 0, rotation: 0, large: false, sweep: false, **)
+          x1, y1, x2, y2, rx, ry, rotation = Scalar.numbers([x1, y1, x2, y2, rx, ry, rotation], context: "absolute arc")
+          unless [large, sweep].all? { it.equal?(true) || it.equal?(false) }
+            ArgumentError.("Arc flags must be Boolean")
+          end
+
+          path(d: "M #{x1} #{y1} A #{rx} #{ry} #{rotation} #{large ? 1 : 0} #{sweep ? 1 : 0} #{x2} #{y2}", **)
+        end
+
+        # Builds an elliptical arc path ending at a relative offset.
+        # @param dx [Numeric] finite x displacement from the starting point
+        # @param dy [Numeric] finite y displacement from the starting point
+        # @param rx [Numeric] finite local x radius
+        # @param ry [Numeric] finite local y radius
+        # @param x [Numeric] finite starting x coordinate
+        # @param y [Numeric] finite starting y coordinate
+        # @param rotation [Numeric] clockwise ellipse rotation in degrees
+        # @param large [Boolean] select the arc exceeding a half turn
+        # @param sweep [Boolean] select increasing parameter angles
+        # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not finite real or a flag is not Boolean
+        # @see #ArcTo
+        def ArcBy(dx:, dy:, rx:, ry:, x: 0, y: 0, rotation: 0, large: false, sweep: false, **)
+          x, y, dx, dy, rx, ry, rotation = Scalar.numbers([x, y, dx, dy, rx, ry, rotation], context: "relative arc")
+          unless [large, sweep].all? { it.equal?(true) || it.equal?(false) }
+            ArgumentError.("Arc flags must be Boolean")
+          end
+
+          path(d: "M #{x} #{y} a #{rx} #{ry} #{rotation} #{large ? 1 : 0} #{sweep ? 1 : 0} #{dx} #{dy}", **)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
         # Builds a line path ending at an absolute point.
-        # @param x2 [Numeric] ending x coordinate
-        # @param y2 [Numeric] ending y coordinate
-        # @param x1 [Numeric] starting x coordinate
-        # @param y1 [Numeric] starting y coordinate
+        # @example Render a rational coordinate as an SVG number
+        #   Sevgi::Graphics.SVG { LineTo(x2: Rational(1, 2), y2: 1) }
+        # @param x2 [Numeric] finite ending x coordinate
+        # @param y2 [Numeric] finite ending y coordinate
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def LineTo(x2:, y2:, x1: 0, y1: 0, **)
+          x1 = Scalar.number(x1, context: "absolute line", field: :x1)
+          y1 = Scalar.number(y1, context: "absolute line", field: :y1)
+          x2 = Scalar.number(x2, context: "absolute line", field: :x2)
+          y2 = Scalar.number(y2, context: "absolute line", field: :y2)
+
           path(d: "M #{x1} #{y1} L #{x2} #{y2}", **)
         end
 
         # Builds a horizontal line path ending at an absolute x coordinate.
-        # @param x2 [Numeric] ending x coordinate
-        # @param x1 [Numeric] starting x coordinate
-        # @param y1 [Numeric] starting y coordinate
+        # @param x2 [Numeric] finite ending x coordinate
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def HLineTo(x2:, x1: 0, y1: 0, **)
+          x1 = Scalar.number(x1, context: "horizontal line", field: :x1)
+          y1 = Scalar.number(y1, context: "horizontal line", field: :y1)
+          x2 = Scalar.number(x2, context: "horizontal line", field: :x2)
+
           path(d: "M #{x1} #{y1} H #{x2}", **)
         end
 
@@ -41,23 +103,36 @@ module Sevgi
         end
 
         # Builds a vertical line path ending at an absolute y coordinate.
-        # @param y2 [Numeric] ending y coordinate
-        # @param x1 [Numeric] starting x coordinate
-        # @param y1 [Numeric] starting y coordinate
+        # @param y2 [Numeric] finite ending y coordinate
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def VLineTo(y2:, x1: 0, y1: 0, **)
+          x1 = Scalar.number(x1, context: "vertical line", field: :x1)
+          y1 = Scalar.number(y1, context: "vertical line", field: :y1)
+          y2 = Scalar.number(y2, context: "vertical line", field: :y2)
+
           path(d: "M #{x1} #{y1} V #{y2}", **)
         end
 
         # Builds a relative line path from angle and length.
-        # @param angle [Numeric] angle in degrees
-        # @param length [Numeric] line length
-        # @param x [Numeric] starting x coordinate
-        # @param y [Numeric] starting y coordinate
+        # @param angle [Numeric] finite angle in degrees, normalized before calculation
+        # @param length [Numeric] finite line length, normalized before calculation
+        # @param x [Numeric] finite starting x coordinate, normalized to an SVG number
+        # @param y [Numeric] finite starting y coordinate, normalized to an SVG number
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
         def LineBy(angle:, length:, x: 0, y: 0, **)
-          dx = length * ::Math.cos(angle.to_f / 180 * ::Math::PI)
-          dy = length * ::Math.sin(angle.to_f / 180 * ::Math::PI)
+          angle, length, x, y = Scalar.numbers([angle, length, x, y], context: "relative line")
+          dx, dy = Scalar.numbers(
+            [
+              length * ::Math.cos(angle.to_f / 180 * ::Math::PI),
+              length * ::Math.sin(angle.to_f / 180 * ::Math::PI)
+            ],
+            context: "relative line result"
+          )
+
           path(d: "M #{x} #{y} l #{dx} #{dy}", **)
         end
 
@@ -74,27 +149,40 @@ module Sevgi
         end
 
         # Builds a relative horizontal line path.
-        # @param length [Numeric] line length
-        # @param x [Numeric] starting x coordinate
-        # @param y [Numeric] starting y coordinate
+        # @param length [Numeric] finite line length
+        # @param x [Numeric] finite starting x coordinate
+        # @param y [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
         def HLineBy(length:, x: 0, y: 0, **)
+          length = Scalar.number(length, context: "horizontal line", field: :length)
+          x = Scalar.number(x, context: "horizontal line", field: :x)
+          y = Scalar.number(y, context: "horizontal line", field: :y)
+
           path(d: "M #{x} #{y} h #{length}", **)
         end
 
         # Builds a square rect.
-        # @param length [Numeric] side length
+        # @param length [Numeric] finite side length
         # @return [Sevgi::Graphics::Element] rect element
+        # @raise [Sevgi::ArgumentError] when length is not a finite real number
         def square(length:, **)
+          length = Scalar.number(length, context: "square", field: :length)
+
           rect(width: length, height: length, **)
         end
 
         # Builds a relative vertical line path.
-        # @param length [Numeric] line length
-        # @param x [Numeric] starting x coordinate
-        # @param y [Numeric] starting y coordinate
+        # @param length [Numeric] finite line length
+        # @param x [Numeric] finite starting x coordinate
+        # @param y [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
         def VLineBy(length:, x: 0, y: 0, **)
+          length = Scalar.number(length, context: "vertical line", field: :length)
+          x = Scalar.number(x, context: "vertical line", field: :x)
+          y = Scalar.number(y, context: "vertical line", field: :y)
+
           path(d: "M #{x} #{y} v #{length}", **)
         end
       end

data/lib/sevgi/graphics/mixtures.rb

@@ -23,26 +23,28 @@ module Sevgi
         mod, document = normalize(mod, document, block)
         ArgumentError.("Mixture name or block required") if mod == Undefined && !block
 
-        document.mixture(mod) unless mod == Undefined
+        document.send(:mixture, mod) unless mod == Undefined
         include_anonymous(document, &block) if block
       end
 
-      def self.anonymous_document?(mod, block)
-        block && mod.is_a?(::Class) && mod <= Graphics::Document::Proto
-      end
+      class << self
+        private
 
-      def self.include_anonymous(document, &block)
-        ::Module.new(&block).tap do |anonymous|
-          document.send(:include, anonymous)
-          document.extend(anonymous.const_get(:ClassMethods)) if anonymous.const_defined?(:ClassMethods, false)
+        def anonymous_document?(mod, block)
+          block && mod.is_a?(::Class) && mod <= Graphics::Document::Proto
         end
-      end
 
-      def self.normalize(mod, document, block)
-        anonymous_document?(mod, block) ? [Undefined, mod] : [mod, document]
-      end
+        def include_anonymous(document, &block)
+          ::Module.new(&block).tap do |anonymous|
+            document.send(:include, anonymous)
+            document.extend(anonymous.const_get(:ClassMethods)) if anonymous.const_defined?(:ClassMethods, false)
+          end
+        end
 
-      private_class_method :anonymous_document?, :include_anonymous, :normalize
+        def normalize(mod, document, block)
+          anonymous_document?(mod, block) ? [Undefined, mod] : [mod, document]
+        end
+      end
     end
   end
 end

data/lib/sevgi/graphics/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Graphics
     # Current graphics component version.
-    VERSION = "0.95.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/sevgi/graphics/xml.rb

@@ -11,8 +11,9 @@ module Sevgi
       NCNAME_CHAR = "#{NCNAME_START}\\-.0-9\u{B7}\u{300}-\u{36F}\u{203F}-\u{2040}".freeze
       NCNAME = "[#{NCNAME_START}][#{NCNAME_CHAR}]*".freeze
       QNAME = /\A#{NCNAME}(?::#{NCNAME})?\z/u
+      ILLEGAL_CHARACTER = /[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u
 
-      private_constant :NCNAME, :NCNAME_CHAR, :NCNAME_START, :QNAME
+      private_constant :NCNAME, :NCNAME_CHAR, :NCNAME_START, :QNAME, :ILLEGAL_CHARACTER
 
       class << self
         # Validates an XML 1.0 string representation.
@@ -104,8 +105,8 @@ module Sevgi
           ArgumentError.("#{context} must be valid UTF-8") unless value.valid_encoding?
 
           text = value.encode("UTF-8")
-          if (codepoint = text.each_codepoint.find { !legal_codepoint?(it) })
-            ArgumentError.("#{context} contains illegal character U+#{format("%04X", codepoint)}")
+          if (match = ILLEGAL_CHARACTER.match(text))
+            ArgumentError.("#{context} contains illegal character U+#{format("%04X", match[0].ord)}")
           end
 
           text
@@ -113,12 +114,6 @@ module Sevgi
           ArgumentError.("#{context} must be valid UTF-8: #{e.message}")
         end
 
-        def legal_codepoint?(codepoint)
-          [0x9, 0xA, 0xD].include?(codepoint) ||
-            (0x20..0xD7FF).cover?(codepoint) ||
-            (0xE000..0xFFFD).cover?(codepoint) ||
-            (0x10000..0x10FFFF).cover?(codepoint)
-        end
       end
     end
 

data/lib/sevgi/graphics.rb

@@ -14,15 +14,44 @@ require_relative "graphics/version"
 
 module Sevgi
   # SVG document builder and DSL namespace.
+  #
+  # A document profile controls root metadata and preambles. A {Canvas} controls
+  # physical size, margins, viewport, and viewBox. {Graphics.SVG} combines them
+  # into an element tree. Library code keeps that tree as an object until it
+  # explicitly renders, validates, saves, or exports it.
+  #
+  # @example Build and render a minimal SVG document
+  #   drawing = Sevgi::Graphics.SVG :minimal, width: 10, height: 10 do
+  #     circle cx: 5, cy: 5, r: 4
+  #   end
+  #   drawing.Render #=> "<svg width=\"10\" height=\"10\">\n  <circle cx=\"5\" cy=\"5\" r=\"4\"/>\n</svg>"
+  # @see https://sevgi.roktas.dev/documents/ SVG construction and profile guide
+  # @see https://sevgi.roktas.dev/compose/ Composition guide
+  # @see https://sevgi.roktas.dev/examples/ Runnable drawing examples
+  # @see Sevgi::Graphics::Document
+  # @see Sevgi::Graphics::Canvas
   module Graphics
-    # @overload canvas(arg = Undefined, **kwargs)
-    #   Builds a canvas from a paper profile or explicit size.
-    #   @param arg [Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined] paper profile or paper object
-    #   @param kwargs [Hash] canvas keyword arguments
+    # @overload canvas(paper, **overrides)
+    #   Builds a canvas from a paper profile with optional field overrides.
+    #   @param paper [Sevgi::Graphics::Paper, Symbol, String] paper object or registered profile
+    #   @param overrides [Hash] canvas field overrides
     #   @return [Sevgi::Graphics::Canvas]
-    #   @raise [Sevgi::ArgumentError] when the paper profile is unknown
+    #   @raise [Sevgi::ArgumentError] when the paper or an override is invalid
+    # @overload canvas(width:, height:, unit: "mm", name: :custom, margins: [])
+    #   Builds a canvas from an explicit size.
+    #   @param width [Numeric] canvas width
+    #   @param height [Numeric] canvas height
+    #   @param unit [Symbol, String] SVG unit
+    #   @param name [Symbol, String] paper name
+    #   @param margins [Array<Numeric>] margin shorthand values
+    #   @return [Sevgi::Graphics::Canvas]
+    #   @raise [Sevgi::ArgumentError] when a required field is omitted or a value is invalid
+    # @example Use the component constructor in library code
+    #   page = Sevgi::Graphics.canvas(:a4, margins: [12, 10])
+    #   icon = Sevgi::Graphics.canvas(width: 24, height: 24, unit: :px)
+    #   [page.name, icon.viewport] # => [:a4, {width: "24.0px", height: "24.0px"}]
     def canvas(...)
-      Graphics::Canvas.from_paper(...)
+      Graphics::Canvas.call(...)
     end
 
     # @overload document(name)
@@ -34,37 +63,52 @@ module Sevgi
     #   Looks up a named profile when both definition keywords are omitted. Supplying `preambles:` or `attributes:`
     #   defines a named profile, or returns an existing profile when every explicitly supplied field matches. Omitted
     #   fields are ignored during existing-profile comparison. Profile containers and strings are copied into the
-    #   process-global, thread-atomic registry; mutable non-container attribute values are stringified once before
-    #   registration. Concurrent identical definitions return the same canonical registered class.
+    #   process-global, thread-atomic registry. Attribute names and nested Hash keys are normalized. Nil attributes are
+    #   omitted. Update suffixes remain available for document-class inheritance. Mutable non-container values are
+    #   stringified once before registration. Concurrent identical definitions return the same registered class.
     #   @param name [Symbol, String] profile name
     #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
-    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes. Nil means an empty Hash
     #   @return [Class] document class
     #   @raise [Sevgi::ArgumentError] when a profile conflicts or metadata is invalid XML, cyclic, or cannot be stringified
     # @overload document(preambles: Undefined, attributes: Undefined)
     #   Defines an anonymous document profile without registering it globally.
     #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
-    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes. Nil means an empty Hash
     #   @return [Class] anonymous document class
     #   @raise [Sevgi::ArgumentError] when metadata is invalid XML, cyclic, or cannot be stringified
     # @return [Class] document class
+    # @example Define, look up, and inspect a named document
+    #   Sevgi::Graphics.document(:card, attributes: {viewBox: "0 0 100 60"})
+    #   Sevgi::Graphics::Document.fetch(:card)              # => the registered document class
+    #   Sevgi::Graphics::Document.profile(:card).attributes # => {viewBox: "0 0 100 60"}
+    # @example Define an anonymous document without changing the registry
+    #   klass = Sevgi::Graphics.document(attributes: {viewBox: "0 0 10 10"})
+    #   klass.profile.name # => nil
+    # @example Define and use a named profile from library code
+    #   Sevgi::Graphics.document(:badge, attributes: {viewBox: "0 0 24 24"})
+    #   drawing = Sevgi::Graphics.SVG(:badge) { circle cx: 12, cy: 12, r: 10 }
+    #   drawing[:viewBox] # => "0 0 24 24"
     def document(name = Undefined, preambles: Undefined, attributes: Undefined)
       Graphics::Document.define(name, preambles:, attributes:)
     end
 
     # Defines or replaces a document profile class.
     # Validation and snapshot capture complete before an existing registration is atomically replaced.
+    # Use the non-bang {#document} for ordinary idempotent definitions. This
+    # bang form is an explicit process-global replacement.
     # @param name [Symbol, String] profile name
     # @param preambles [Array<String>, nil] document preamble lines
-    # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
+    # @param attributes [Hash, nil] default root attributes. Nil means an empty Hash
     # @return [Class] document class
     # @raise [Sevgi::ArgumentError] when the name or metadata is invalid XML, cyclic, or cannot be stringified
     def document!(name, preambles: [], attributes: {})
       Graphics::Document.define(name, preambles:, attributes:, overwrite: true)
     end
 
-    # Defines a paper profile unless the same profile already exists. Registration is process-global and thread-atomic;
-    # an identical concurrent definition is idempotent and a conflicting definition is rejected.
+    # Defines a paper profile unless the same profile already exists.
+    # Registration is process-global and thread-atomic. Identical concurrent definitions are idempotent. Conflicting
+    # definitions are rejected.
     # @param width [Numeric] paper width
     # @param height [Numeric] paper height
     # @param name [Symbol, String] profile name
@@ -78,6 +122,7 @@ module Sevgi
     end
 
     # Defines or replaces a paper profile.
+    # Use this only when replacing the process-global meaning of a name is intentional.
     # @param width [Numeric] paper width
     # @param height [Numeric] paper height
     # @param name [Symbol, String] profile name
@@ -85,23 +130,29 @@ module Sevgi
     # @return [Symbol, String] original profile name
     # @raise [Sevgi::ArgumentError] when the profile is invalid or the profile name is reserved
     def paper!(width, height, name = :custom, unit: "mm")
-      name.tap { Graphics::Paper.define(name, width:, height:, unit:) }
+      name.tap { Graphics::Paper.define(name, width:, height:, unit:, overwrite: true) }
     end
 
-    # Builds an SVG root document.
-    # @param document [Symbol, String, Class] document profile name or document class
+    # Builds an SVG root element tree without rendering it.
+    #
+    # The first argument selects root metadata, or supplies the canvas while using the default profile. The second
+    # supplies canvas attributes when the first argument is a profile. Keyword attributes are applied after both.
+    # @param document [Symbol, String, Class, Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper] document profile,
+    #   document class, or canvas input that uses the default profile
     # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] canvas input
     # @yield evaluates the drawing DSL in the root element
     # @yieldreturn [Object] ignored block result
     # @return [Sevgi::Graphics::Document::Proto] SVG root element
     # @raise [Sevgi::ArgumentError] when the document/canvas profile or root XML attributes are invalid
     def SVG(document = :default, canvas = Undefined, **, &block)
+      if canvas.equal?(Undefined) && (document.is_a?(Canvas) || document.is_a?(Paper))
+        document, canvas = :default, document
+      end
+
       Graphics::Document.(document, canvas, **, &block)
     end
 
     extend self
   end
 
-  # Top-level alias for the graphics DSL namespace.
-  SVG = Graphics
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-graphics
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,15 +15,15 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
-description: Provides an extensible DSL for creating SVG content.
+        version: 1.0.0
+description: Builds and renders SVG document trees from Ruby.
 email: roktas@gmail.com
 executables: []
 extensions: []
@@ -39,6 +39,7 @@ files:
 - lib/sevgi/graphics/auxiliary/content.rb
 - lib/sevgi/graphics/auxiliary/margin.rb
 - lib/sevgi/graphics/auxiliary/paper.rb
+- lib/sevgi/graphics/auxiliary/path.rb
 - lib/sevgi/graphics/auxiliary/scalar.rb
 - lib/sevgi/graphics/auxiliary/sizes.rb
 - lib/sevgi/graphics/document.rb
@@ -92,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Core DSL for the Sevgi toolkit.
+summary: Core SVG DSL for Sevgi.
 test_files: []