sevgi-graphics 0.73.2 → 0.94.0

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

@@ -3,7 +3,14 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for SVG transform attributes.
       module Transform
+        # Aligns an inner box inside an outer box.
+        # @param position [Symbol, String, nil] alignment name
+        # @param inner [#width, #height, nil] inner box
+        # @param outer [#width, #height, nil] outer box
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when alignment is unsupported
         def Align(position, inner:, outer:)
           return self unless position && inner && outer
 
@@ -15,34 +22,47 @@ module Sevgi
           end
         end
 
+        # Appends a scale(-1, -1) transform.
+        # @return [Sevgi::Graphics::Element] self
         def Flip
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, 1) scale(1, 1)"
+            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, -1)"
           end
         end
 
+        # Appends a horizontal flip transform.
+        # @return [Sevgi::Graphics::Element] self
         def FlipX
           tap do
             attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, 1)"
           end
         end
 
+        # Appends a vertical flip transform.
+        # @return [Sevgi::Graphics::Element] self
         def FlipY
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(1, -11)"
+            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(1, -1)"
           end
         end
 
+        # Appends a six-value SVG matrix transform.
+        # @param values [Array<Numeric>] matrix values
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when exactly six values are not supplied
         def Matrix(*values)
           tap do
             ArgumentError.("Incorrect transform matrix (six values required): #{values}") if values.size != 6
 
-            next if values.map(&:to_f).all? { it == 0.0 }
-
             attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "matrix(#{values.join(" ")})"
           end
         end
 
+        # Appends an SVG rotate transform.
+        # @param a [Numeric] angle in degrees
+        # @param origin [Array<Numeric>] optional x and y origin
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when origin is not two coordinates
         def Rotate(a, *origin)
           tap do
             if !origin.empty? && origin.size != 2
@@ -55,28 +75,39 @@ module Sevgi
           end
         end
 
-        def Rotate90(...) = Rotate(90, ...)
-
-        def Rotate09(...) = Rotate(-90, ...)
-
+        # @overload RotateRight(*origin)
+        #   Appends a 90-degree SVG rotate transform.
+        #   @param origin [Array<Numeric>] optional x and y origin
+        #   @return [Sevgi::Graphics::Element] self
+        def RotateRight(...) = Rotate(90, ...)
+
+        # @overload RotateLeft(*origin)
+        #   Appends a -90-degree SVG rotate transform.
+        #   @param origin [Array<Numeric>] optional x and y origin
+        #   @return [Sevgi::Graphics::Element] self
+        def RotateLeft(...) = Rotate(-90, ...)
+
+        # Appends an SVG scale transform.
+        # @param x [Numeric] x scale, or uniform scale when y is nil
+        # @param y [Numeric, nil] y scale
+        # @return [Sevgi::Graphics::Element] self
         def Scale(x, y = nil)
           tap do
-            next if x.to_f == 0.0 && (y.nil? || y.to_f == 0.0)
-
             attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(#{(y ? [x, y] : [x]).join(", ")})"
           end
         end
 
-        def Scale!(...)
-          Scale(...).tap do
-            attributes[:"vector-effect"] = "non-scaling-stroke" unless attributes[:"vector-effect"]
-          end
-        end
-
+        # Appends a skew transform through an SVG matrix.
+        # @param ax [Numeric] x skew angle in degrees
+        # @param ay [Numeric] y skew angle in degrees
+        # @return [Sevgi::Graphics::Element] self
         def Skew(ax, ay)
           Matrix(1.0, ::Math.tan(ay / 180.0 * ::Math::PI), ::Math.tan(ax / 180.0 * ::Math::PI), 1.0, 0.0, 0.0)
         end
 
+        # Appends an SVG skewX transform.
+        # @param a [Numeric] angle in degrees
+        # @return [Sevgi::Graphics::Element] self
         def SkewX(a)
           tap do
             next if a.to_f == 0.0
@@ -85,6 +116,9 @@ module Sevgi
           end
         end
 
+        # Appends an SVG skewY transform.
+        # @param a [Numeric] angle in degrees
+        # @return [Sevgi::Graphics::Element] self
         def SkewY(a)
           tap do
             next if a.to_f == 0.0
@@ -93,6 +127,10 @@ module Sevgi
           end
         end
 
+        # Appends an SVG translate transform.
+        # @param x [Numeric] x translation
+        # @param y [Numeric, nil] y translation
+        # @return [Sevgi::Graphics::Element] self
         def Translate(x, y = nil)
           tap do
             next if x.to_f == 0.0 && (y.nil? || y.to_f == 0.0)

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

@@ -3,18 +3,38 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for floating text, comments, and inherited internal attributes.
       module Underscore
+        # Creates a floating content element.
+        # @param contents [Array<Object>] text or content objects
+        # @return [Sevgi::Graphics::Element] floating element
         def _(*contents)
           Element(:_, *contents)
         end
 
+        # Adds an XML comment.
+        # @param comment [Object] comment text
+        # @return [Sevgi::Graphics::Element] floating comment element
+        # @raise [Sevgi::ArgumentError] when comment text would produce malformed XML
         def Comment(comment)
+          comment = comment.to_s
+
+          ArgumentError.("XML comment must not contain '--'") if comment.include?("--")
+          ArgumentError.("XML comment must not end with '-'") if comment.end_with?("-")
+
           _(Content.verbatim("<!-- #{comment} -->"))
         end
 
+        # Merges internal attributes from the document root, ancestors, and this element.
+        # Only the direct root-to-self ancestor chain participates; sibling subtrees are ignored. When the same key is
+        # present on multiple chain elements, the nearest element to the receiver wins.
+        # @return [Hash] merged internal attributes
         def Ancestral
+          chain = []
+          TraverseUp { |element| chain.unshift(element) }
+
           {}.tap do |result|
-            Root.Traverse() { |element| result.merge!(element[:_]) if element.has?(:_) }
+            chain.each { |element| result.merge!(element[:_]) if element.has?(:_) }
           end
         end
       end

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

@@ -3,19 +3,28 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for SVG standard validation.
       module Validate
+        # Returns text content used as SVG character data.
+        # @return [String, nil] joined text content or nil
         def CData
           return if !contents || contents.empty?
 
           Content.text(contents)
         end
 
+        # Reports whether a namespace is available on this element or an ancestor.
+        # @param name [Symbol, String] namespace suffix without xmlns:
+        # @return [Boolean]
         def NS?(name)
           self.class.attributes.key?(key = :"xmlns:#{name}") || TraverseUp { Stay(true) if it.has?(key) } || false
         end
 
         require "sevgi/standard"
 
+        # Validates this subtree against the SVG standard metadata.
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ValidationError] when SVG validation fails
         def Validate
           Traverse do |element|
             Standard.conform(
@@ -27,7 +36,12 @@ module Sevgi
           end
         end
 
-      rescue ::LoadError
+      rescue ::LoadError => e
+        raise unless e.path == "sevgi/standard"
+
+        # @overload Validate
+        #   No-op validation fallback when sevgi/standard is unavailable.
+        #   @return [nil]
         def Validate(...)
         end
       end

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

@@ -3,15 +3,31 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL wrappers for common SVG shapes and content patterns.
       module Wrappers
-        def Cline(x2:, y2:, x1: 0, y1: 0, **)
+        # 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
+        # @return [Sevgi::Graphics::Element] path element
+        def LineTo(x2:, y2:, x1: 0, y1: 0, **)
           path(d: "M #{x1} #{y1} L #{x2} #{y2}", **)
         end
 
-        def Hline(x2:, x1: 0, y1: 0, **)
+        # 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
+        # @return [Sevgi::Graphics::Element] path element
+        def HLineTo(x2:, x1: 0, y1: 0, **)
           path(d: "M #{x1} #{y1} H #{x2}", **)
         end
 
+        # Builds a titled SVG symbol.
+        # @param name [String] human-readable symbol name
+        # @param kwargs [Hash] symbol attributes
+        # @return [Sevgi::Graphics::Element] symbol element
         def Symbol(name, **kwargs, &block)
           id = (words = name.split).map(&:downcase).join("-")
           title = words.map(&:capitalize).join(" ")
@@ -22,39 +38,60 @@ module Sevgi
           end
         end
 
-        def Vline(y2:, x1: 0, y1: 0, **)
+        # 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
+        # @return [Sevgi::Graphics::Element] path element
+        def VLineTo(y2:, x1: 0, y1: 0, **)
           path(d: "M #{x1} #{y1} V #{y2}", **)
         end
 
-        def cline(angle:, length:, x: 0, y: 0, **)
+        # 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
+        # @return [Sevgi::Graphics::Element] path element
+        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)
           path(d: "M #{x} #{y} l #{dx} #{dy}", **)
         end
 
-        def css(hash, **)
-          style(Content.css(hash), type: "text/css", **)
-        end
+        # Builds a style element with CSS content.
+        # @param hash [Hash, nil] CSS rules
+        # @param attributes [Hash] style attributes or CSS rules when hash is nil
+        # @return [Sevgi::Graphics::Element] style element
+        # @raise [Sevgi::ArgumentError] when CSS content is not a hash
+        def css(hash = nil, **attributes)
+          hash, attributes = attributes, {} unless hash
 
-        def cxline(angle:, dx:, x: 0, y: 0, **)
-          dy = dx * ::Math.tan(angle.to_f / 180 * ::Math::PI)
-          path(d: "M #{x} #{y} l #{dx} #{dy}", **)
-        end
-
-        def cyline(angle:, dy:, x: 0, y: 0, **)
-          dx = dy / ::Math.tan(angle.to_f / 180 * ::Math::PI)
-          path(d: "M #{x} #{y} l #{dx} #{dy}", **)
+          style(Content.css(hash), type: "text/css", **attributes)
         end
 
-        def hline(length:, x: 0, y: 0, **)
+        # Builds a relative horizontal line path.
+        # @param length [Numeric] line length
+        # @param x [Numeric] starting x coordinate
+        # @param y [Numeric] starting y coordinate
+        # @return [Sevgi::Graphics::Element] path element
+        def HLineBy(length:, x: 0, y: 0, **)
           path(d: "M #{x} #{y} h #{length}", **)
         end
 
+        # Builds a square rect.
+        # @param length [Numeric] side length
+        # @return [Sevgi::Graphics::Element] rect element
         def square(length:, **)
           rect(width: length, height: length, **)
         end
 
-        def vline(length:, x: 0, y: 0, **)
+        # Builds a relative vertical line path.
+        # @param length [Numeric] line length
+        # @param x [Numeric] starting x coordinate
+        # @param y [Numeric] starting y coordinate
+        # @return [Sevgi::Graphics::Element] path element
+        def VLineBy(length:, x: 0, y: 0, **)
           path(d: "M #{x} #{y} v #{length}", **)
         end
       end

data/lib/sevgi/graphics/mixtures.rb

@@ -2,11 +2,43 @@
 
 module Sevgi
   module Graphics
+    # Mixins that extend document classes with DSL helper methods.
     module Mixtures
-      def self.mixin(mod, document = Graphics::Document::Base, &block)
-        document.mixture(mod)
-        document.mixture(::Module.new(&block)) if block
+      # @overload mixin(mod, document = Graphics::Document::Base, &block)
+      #   Includes a named mixture and optional anonymous extension into a document class.
+      #   @param mod [Symbol, String] mixture constant name
+      #   @param document [Class] document class receiving the mixture
+      #   @return [Module, nil] optional anonymous mixture when a block is given
+      #   @raise [NameError] when the mixture does not exist
+      # @overload mixin(document = Graphics::Document::Base, &block)
+      #   Includes only an anonymous extension into a document class.
+      #   @param document [Class] document class receiving the mixture
+      #   @return [Module] anonymous mixture
+      #   @raise [Sevgi::ArgumentError] when no named mixture or block is given
+      def self.mixin(mod = Undefined, document = Graphics::Document::Base, &block)
+        mod, document = normalize(mod, document, block)
+        ArgumentError.("Mixture name or block required") if mod == Undefined && !block
+
+        document.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
+
+      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)
+        end
+      end
+
+      def self.normalize(mod, document, block)
+        anonymous_document?(mod, block) ? [Undefined, mod] : [mod, document]
       end
+
+      private_class_method :anonymous_document?, :include_anonymous, :normalize
     end
   end
 end

data/lib/sevgi/graphics/version.rb

@@ -2,6 +2,7 @@
 
 module Sevgi
   module Graphics
-    VERSION = "0.73.2"
+    # Current graphics component version.
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/graphics.rb

@@ -3,7 +3,7 @@
 require "sevgi/function"
 
 require_relative "graphics/attribute"
-require_relative "graphics/auxilary"
+require_relative "graphics/auxiliary"
 require_relative "graphics/element"
 require_relative "graphics/mixtures"
 
@@ -12,23 +12,88 @@ require_relative "graphics/document"
 require_relative "graphics/version"
 
 module Sevgi
+  # SVG document builder and DSL namespace.
   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
+    #   @return [Sevgi::Graphics::Canvas]
+    #   @raise [Sevgi::ArgumentError] when the paper profile is unknown
     def canvas(...)
-      Graphics::Canvas.(...)
+      Graphics::Canvas.from_paper(...)
     end
 
-    def document(name = :default, preambles: [], attributes: {})
-      Class.new(Graphics::Document::Base) { document(name, preambles:, attributes:) }
+    # @overload document(name)
+    #   Looks up an existing document profile by name.
+    #   @param name [Symbol, String] profile name
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when the profile is unknown
+    # @overload document(name, preambles: Undefined, attributes: Undefined)
+    #   Defines a named document profile, or returns an existing profile when every explicitly supplied field matches.
+    #   Omitted fields are ignored during existing-profile comparison. Profile inputs are copied into the registry.
+    #   @param name [Symbol, String] profile name
+    #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+    #   @param attributes [Hash, Sevgi::Undefined] default root attributes
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
+    # @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, Sevgi::Undefined] default root attributes
+    #   @return [Class] anonymous document class
+    #   @raise [Sevgi::ArgumentError] when profile input is invalid
+    # @return [Class] document class
+    def document(name = Undefined, preambles: Undefined, attributes: Undefined)
+      Graphics::Document.define(name, preambles:, attributes:)
     end
 
+    # Defines or replaces a document profile class.
+    # @param name [Symbol, String] profile name
+    # @param preambles [Array<String>, nil] document preamble lines
+    # @param attributes [Hash] default root attributes
+    # @return [Class] document class
+    # @raise [Sevgi::ArgumentError] when the profile name is invalid
+    def document!(name, preambles: [], attributes: {})
+      Graphics::Document.define(name, preambles:, attributes:, overwrite: true)
+    end
+
+    # Defines a paper profile unless the same profile already exists.
+    # @param width [Numeric] paper width
+    # @param height [Numeric] paper height
+    # @param name [Symbol, String] profile name
+    # @param unit [Symbol, String] SVG unit
+    # @return [Symbol, String] original profile name
+    # @raise [Sevgi::ArgumentError] when the profile is invalid or an existing profile has different dimensions
     def paper(width, height, name = :custom, unit: "mm")
-      name.tap { Graphics::Paper.define(name, width:, height:, unit:) unless Graphics::Paper.exist?(name) }
+      profile = Graphics::Paper[width, height, unit, name]
+
+      if Graphics::Paper.exist?(name)
+        ArgumentError.("Paper already defined differently: #{name}") unless Graphics::Paper.public_send(name) == profile
+      else
+        Graphics::Paper.define(name, width:, height:, unit:)
+      end
+
+      name
     end
 
+    # Defines or replaces a paper profile.
+    # @param width [Numeric] paper width
+    # @param height [Numeric] paper height
+    # @param name [Symbol, String] profile name
+    # @param unit [Symbol, String] SVG unit
+    # @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:) }
     end
 
+    # Builds an SVG root document.
+    # @param document [Symbol, String, Class] document profile name or document class
+    # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] canvas input
+    # @param block [Proc, nil] DSL block evaluated in the root element
+    # @return [Sevgi::Graphics::Document::Proto] SVG root element
+    # @raise [Sevgi::ArgumentError] when the document or canvas profile is unknown
     def SVG(document = :default, canvas = Undefined, **, &block)
       Graphics::Document.(document, canvas, **, &block)
     end
@@ -36,5 +101,6 @@ module Sevgi
     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.73.2
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,27 +15,30 @@ 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
 description: Provides an extensible DSL for creating SVG content.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - lib/sevgi/graphics.rb
 - lib/sevgi/graphics/attribute.rb
-- lib/sevgi/graphics/auxilary.rb
-- lib/sevgi/graphics/auxilary/canvas.rb
-- lib/sevgi/graphics/auxilary/content.rb
-- lib/sevgi/graphics/auxilary/margin.rb
-- lib/sevgi/graphics/auxilary/paper.rb
+- lib/sevgi/graphics/auxiliary.rb
+- lib/sevgi/graphics/auxiliary/canvas.rb
+- lib/sevgi/graphics/auxiliary/content.rb
+- lib/sevgi/graphics/auxiliary/margin.rb
+- lib/sevgi/graphics/auxiliary/paper.rb
 - lib/sevgi/graphics/document.rb
 - lib/sevgi/graphics/document/base.rb
 - lib/sevgi/graphics/document/default.rb
@@ -79,7 +82,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:
   - - ">="

data/lib/sevgi/graphics/auxilary/canvas.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-require "forwardable"
-
-module Sevgi
-  module Graphics
-    class Canvas
-      def self.call(arg = Undefined, **kwargs)
-        case arg
-        when Undefined
-          new(**kwargs)
-        when ::Symbol, ::String
-          new(**Paper.public_send(arg).to_h, **kwargs)
-        else
-          ArgumentError.("Argument must be a Paper symbol: #{arg}")
-        end
-      end
-
-      extend Forwardable
-
-      def_delegators :@margin, *Margin.members
-      def_delegators :@size, *Paper.members
-
-      attr_reader :size, :margin, :inner
-
-      def initialize(width:, height:, unit: "mm", name: :custom, margins: [])
-        @size = Paper[width, height, unit, name]
-        @margin = Margin[*margins]
-
-        compute
-        freeze
-      end
-
-      def attributes(...) = {**viewport, viewBox: viewbox(...)}
-
-      def conforming(...) = self.class.conforming(self, ...)
-
-      def viewport = {width: "#{width}#{unit}", height: "#{height}#{unit}"}
-
-      def viewbox(origin = Undefined) = prettify(*originate(origin), width, height).join(" ")
-
-      def with(**kwargs) = self.class.new(**size.to_h, margins: kwargs.fetch(:margins, margin.to_a))
-
-      private
-
-      def compute
-        @inner = size.with(width: width - margin.left - margin.right, height: height - margin.top - margin.bottom)
-      end
-
-      def originate(origin)
-        case origin
-        when Undefined
-          [-margin.left, -margin.top]
-        when ::Numeric, ::NilClass
-          [origin.to_f, origin.to_f]
-        when ::Array
-          pair(origin)
-        else
-          ArgumentError.("Canvas origin must be an Array")
-        end
-      end
-
-      def prettify(*floats)
-        floats.map { (it % 1).zero? ? it.to_i : it }
-      end
-
-      def pair(array)
-        array.size == 2 ? array.map(&:to_f) : ArgumentError.("Argument must be an Array of size 2")
-      end
-    end
-  end
-end