sevgi-graphics 0.73.2 → 0.93.1

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.93.1"
   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,74 @@ 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:) }
+    # Defines or returns a document profile class.
+    # @param name [Symbol, String, Sevgi::Undefined] profile name, or Undefined for an anonymous profile
+    # @param preambles [Array<String>, nil] document preamble lines
+    # @param attributes [Hash] default root attributes
+    # @return [Class] document class
+    # @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
+    def document(name = Undefined, preambles: [], attributes: {})
+      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 +87,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.93.1
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,27 +15,28 @@ 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
 description: Provides an extensible DSL for creating SVG content.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- 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

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

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

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Sevgi
-  module Graphics
-    class Content
-      attr_reader :content
-
-      def initialize(content) = @content = content
-
-      def render(_renderer, _depth) = raise NoMethodError, "#{self.class}#render must be implemented"
-
-      def to_s = content.to_s
-
-      def self.cdata(...) = CData.new(...)
-
-      def self.contents(*args) = args.map { it.is_a?(Content) ? it : encoded(it) }
-
-      def self.css(...) = CSS.new(...)
-
-      def self.encoded(...) = Encoded.new(...)
-
-      def self.text(contents) = Array(contents).join("\n")
-
-      def self.verbatim(...) = Verbatim.new(...)
-
-      class CData < Content
-        def render(renderer, depth)
-          depth += 1
-
-          renderer.append(depth, "<![CDATA[")
-          renderer.append(depth + 1, *Array(content))
-          renderer.append(depth, "]]>")
-        end
-      end
-
-      class CSS < Content
-        def initialize(content)
-          ArgumentError.("CSS content must be a hash: #{content}") unless content.is_a?(::Hash)
-
-          super
-        end
-
-        # rubocop:disable Metrics/MethodLength
-        def render(renderer, depth)
-          depth += 1
-
-          renderer.append(depth, "<![CDATA[")
-
-          depth += 1
-          content.each do |rule, styles|
-            case styles
-            when ::Hash
-              renderer.append(depth, "#{rule} {")
-              renderer.append(depth + 1, *styles.map { |key, value| "#{key}: #{value};" })
-              renderer.append(depth, "}")
-            when ::String, ::Symbol, ::Numeric
-              renderer.append(depth, "#{rule}: #{styles};")
-            else
-              ArgumentError.("Malformed style: #{styles}")
-            end
-          end
-
-          depth -= 1
-
-          renderer.append(depth, "]]>")
-        end
-        # rubocop:enable Metrics/MethodLength
-      end
-
-      class Encoded < Content
-        def to_s = content.encode(xml: :text)
-
-        def render(renderer, depth) = renderer.append(depth + 1, to_s)
-      end
-
-      class Verbatim < Content
-        def render(renderer, depth) = renderer.append(depth + 1, to_s)
-      end
-    end
-  end
-end

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

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Sevgi
-  module Graphics
-    Margin = Data.define(:top, :right, :bottom, :left) do
-      include Comparable
-
-      def initialize(top: nil, right: nil, bottom: nil, left: nil)
-        case [top, right, bottom, left]
-        in [Numeric, Numeric, Numeric, Numeric]
-          nil
-        in [Numeric, Numeric, Numeric, NilClass]
-          left = right
-        in [Numeric, Numeric, NilClass, NilClass]
-          bottom, left = top, right
-        in [Numeric, NilClass, NilClass, NilClass]
-          bottom, left, right = top, top, top
-        in [NilClass, NilClass, NilClass, NilClass]
-          top, bottom, left, right = 0, 0, 0, 0
-        end
-
-        super(top: Float(top), right: Float(right), bottom: Float(bottom), left: Float(left))
-      end
-
-      def <=>(other) = deconstruct <=> other.deconstruct
-
-      def change(h, v) = self.class[top + v, right + h, bottom + v, left + h]
-
-      def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
-
-      def hash = [self.class, *deconstruct].hash
-
-      def htotal = left + right
-
-      def vtotal = top + bottom
-
-      alias_method :==, :eql?
-      alias_method :to_a, :deconstruct
-
-      def self.margin(array)
-        self[
-          *(array = Array(array)[0...(size = Margin.members.size)]).fill(nil, array.size, size - array.size)
-        ]
-      end
-
-      def self.zero = (@zero ||= self[0.0, 0.0, 0.0, 0.0])
-    end
-  end
-end

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

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-module Sevgi
-  module Graphics
-    Paper = Data.define(:width, :height, :unit, :name) do
-      include Comparable
-
-      def initialize(width:, height:, unit: "mm", name: :custom)
-        super(width: Float(width), height: Float(height), unit: unit.to_sym, name: name.to_sym)
-      end
-
-      def <=>(other) = deconstruct <=> other.deconstruct
-
-      def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
-
-      def hash = [self.class, *deconstruct].hash
-
-      def longest = [width, height].max
-
-      def shortest = [width, height].min
-
-      alias_method :==, :eql?
-
-      def self.define!(name, ...)
-        raise ArgumentError, "Paper already defined: #{name}" if exist?(name)
-
-        define(name, ...)
-      end
-
-      def self.exist?(name) = respond_to?(name)
-
-      def self.define(name, **spec)
-        singleton_class.attr_reader(name)
-        instance_variable_set("@#{name}", new(name:, **spec))
-      end
-
-      {
-        a0: [841, 1189, "mm"],
-        a1: [594, 841, "mm"],
-        a2: [420, 594, "mm"],
-        a3: [297, 420, "mm"],
-        a4: [210, 297, "mm"],
-        a5: [148, 210, "mm"],
-        a6: [105, 148, "mm"],
-        a7: [740, 105, "mm"],
-        a8: [520, 74, "mm"],
-        a9: [370, 52, "mm"],
-        a10: [260, 37, "mm"],
-
-        b0: [1000, 1414, "mm"],
-        b1: [707, 1000, "mm"],
-        b2: [500, 707, "mm"],
-        b3: [353, 500, "mm"],
-        b4: [250, 353, "mm"],
-        b5: [176, 250, "mm"],
-        b6: [125, 176, "mm"],
-        b7: [88, 125, "mm"],
-        b8: [62, 88, "mm"],
-        b9: [44, 62, "mm"],
-        b10: [31, 44, "mm"],
-
-        c0: [917, 1297, "mm"],
-        c1: [648, 917, "mm"],
-        c2: [458, 648, "mm"],
-        c3: [324, 458, "mm"],
-        c4: [229, 324, "mm"],
-        c5: [162, 229, "mm"],
-        c6: [114, 162, "mm"],
-        c7: [81, 114, "mm"],
-        c8: [57, 81, "mm"],
-        c9: [40, 57, "mm"],
-        c10: [28, 40, "mm"],
-
-        business: [85, 55, "mm"],
-        large: [130, 210, "mm"],
-        passport: [88, 125, "mm"],
-        pocket: [90, 140, "mm"],
-        travelers: [110, 210, "mm"],
-        us: [216, 279, "mm"],
-        xlarge: [190, 250, "mm"],
-
-        icon16: [16, 16, "px"],
-        icon32: [32, 32, "px"],
-        icon64: [64, 64, "px"],
-        icon128: [128, 128, "px"],
-        icon256: [256, 256, "px"],
-        icon512: [512, 512, "px"]
-      }.each { |name, (width, height, unit)| define(name, width:, height:, unit:) }
-
-      class << self
-        alias_method :default, :a4
-      end
-    end
-  end
-end

data/lib/sevgi/graphics/auxilary.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "auxilary/margin"
-require_relative "auxilary/paper"
-
-require_relative "auxilary/canvas"
-require_relative "auxilary/content"