sevgi-graphics 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f037bca5ff8f5c96deec6ac271ccb0b0649f5a9ee8c3cf9aa4f2ec04a14a593d
-  data.tar.gz: e880612eb0dd48783a24e0ca71fbde7dbf10faa7b84d640230d8beeeb831144d
+  metadata.gz: 74dd7631f2aeaa252c236f7dd1c372bd4860ebca07f23b787329aebdc04862b1
+  data.tar.gz: 04617a19db7b7e6485037ddd534f115f8c89d21dfd62cfa69de9fd8a6ff5a08f
 SHA512:
-  metadata.gz: 95d77cf9671b69ea7cc16435187f3f700ef2062ea21e6d09b8261eef147c1ae533ce37f6bd403cbcdf5da98a6ad328e10be9a1fc1fc73597985715bc8767f490
-  data.tar.gz: 2d376cdca8ce4f05ae58130590cabba02e88013ee3bd774f773cf8c0befab591bb2f1e5c4ed62fb0841748079df06961424f6646fb1163164ad26dd44f16e5dc
+  metadata.gz: 0acdf02ba08e49a7c3673e3457befc3c5270acb5fe05fd9985ec9d02b32f1231c79bc4127176ea3ebead9e3b9cd6e628af024e5de0aee951578eb72ff58e68d2
+  data.tar.gz: 90794ba32fd574c0747c61d71a7f0a47914bbf67a43e4239492cd97a8d9beec70cb482a9f2da5e095bf61e725f1dcafd2d4e0054561b884e0a6c32be5b8e2ee7

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Sevgi Graphics follows the root Sevgi release notes:
+https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Graphics is distributed under the GNU General Public License v3.0 or later.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+Full project license: https://github.com/roktas/sevgi/blob/main/LICENSE

data/README.md

@@ -0,0 +1,37 @@
+# Sevgi Graphics
+
+Core SVG DSL, document profiles, and rendering behavior.
+
+## Install
+
+```sh
+gem install sevgi-graphics
+```
+
+## Require
+
+```ruby
+require "sevgi/graphics"
+```
+
+## Example
+
+```ruby
+doc = Sevgi::Graphics.SVG(:minimal) { rect(width: 3, height: 5) }
+doc.call
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-graphics
+- Source: https://github.com/roktas/sevgi/tree/main/graphics
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/graphics/attribute.rb

@@ -4,20 +4,36 @@
 
 module Sevgi
   module Graphics
+    # Internal store syntax; not part of the SVG DSL command surface.
     ATTRIBUTE_INTERNAL_PREFIX = "-"
+
+    # Attribute suffix that merges new values into an existing attribute.
     ATTRIBUTE_UPDATE_SUFFIX = "+"
 
+    # Attribute name normalization helpers.
+    # @api private
     module Attribute
+      # Attribute identifier helpers.
+      # @api private
       module Ident
+        # Reports whether an attribute is internal to Sevgi rendering.
+        # @param given [String, Symbol] attribute name
+        # @return [Boolean]
         def internal?(given)
           (@internal ||= {})[given] ||= given.start_with?(ATTRIBUTE_INTERNAL_PREFIX)
         end
 
+        # Returns the normalized attribute id.
+        # @param given [String, Symbol] attribute name
+        # @return [Symbol]
         def id(given)
           (@id ||= {})[given] ||= (updateable?(given) ? given.to_s.delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : given)
             .to_sym
         end
 
+        # Reports whether an attribute uses merge/update syntax.
+        # @param given [String, Symbol] attribute name
+        # @return [Boolean]
         def updateable?(given)
           (@updateable ||= {})[given] ||= given.end_with?(ATTRIBUTE_UPDATE_SUFFIX)
         end
@@ -25,38 +41,74 @@ module Sevgi
 
       extend Ident
 
+      # Returns the text form used for an XML attribute value before escaping.
+      # @param value [Object] attribute value
+      # @return [String]
+      # @api private
+      def self.xml_text(value)
+        case value
+        when ::Hash
+          value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")
+        when ::Array
+          value.join(" ")
+        else
+          value.to_s
+        end
+      end
+
+      # Mutable SVG attribute store with Sevgi update syntax.
       class Store
+        # Creates an attribute store.
+        # @param attributes [Hash] initial attributes
+        # @return [void]
         def initialize(attributes = {})
           @store = {}
 
           import(attributes)
         end
 
+        # Imports attributes into the store.
+        # @param attributes [Hash] attributes to merge
+        # @return [Hash] internal store
         def import(attributes)
           hash = attributes
             .compact
             .to_a
             .to_h do |key, value|
-              [key.to_sym, value.is_a?(::Hash) ? value.transform_keys!(&:to_sym) : value]
+              [key.to_sym, import_value(value)]
             end
 
           @store.merge!(hash)
         end
 
+        # Returns an attribute by normalized key.
+        # @param key [String, Symbol] attribute key
+        # @return [Object, nil]
         def [](key)
           @store[Attribute.id(key)]
         end
 
+        # Assigns an attribute value.
+        # @param key [String, Symbol] attribute key
+        # @param value [Object, nil] attribute value; nil is ignored
+        # @return [Object, nil] assigned value or nil
+        # @raise [Sevgi::ArgumentError] when update syntax receives incompatible values
+        # @raise [Sevgi::ArgumentError] when update syntax receives an unsupported value type
         def []=(key, value)
           return if value.nil?
 
           @store[id = Attribute.id(key)] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
         end
 
+        # Deletes an attribute by normalized key.
+        # @param key [String, Symbol] attribute key
+        # @return [Object, nil] deleted value
         def delete(key)
           @store.delete(Attribute.id(key))
         end
 
+        # Returns public attributes ready for rendering.
+        # @return [Hash]
         def export
           hash = @store.reject { |id, _| Attribute.internal?(id) }
           return hash unless hash.key?(:id)
@@ -65,10 +117,16 @@ module Sevgi
           {id: hash.delete(:id), **hash}
         end
 
+        # Reports whether an attribute exists.
+        # @param key [String, Symbol] attribute key
+        # @return [Boolean]
         def has?(key)
           @store.key?(Attribute.id(key))
         end
 
+        # Copies the attribute store.
+        # @param original [Sevgi::Graphics::Attribute::Store] store to copy
+        # @return [void]
         def initialize_copy(original)
           @store = {}
           original.store.each { |key, value| @store[key] = value.dup }
@@ -76,14 +134,20 @@ module Sevgi
           super
         end
 
+        # Returns public attribute names.
+        # @return [Array<Symbol>]
         def list
           export.keys
         end
 
+        # Returns the internal attribute hash.
+        # @return [Hash]
         def to_h
           @store
         end
 
+        # Returns rendered XML attribute lines.
+        # @return [Array<String>]
         def to_xml_lines
           export.map { |id, value| to_xml(id, value) }
         end
@@ -94,11 +158,25 @@ module Sevgi
 
         private
 
+        # Returns a caller-owned value copy for import.
+        # @param value [Object] attribute value
+        # @return [Object] imported value
+        def import_value(value)
+          case value
+          when ::Hash
+            value.transform_keys(&:to_sym)
+          when ::Array
+            value.dup
+          else
+            value
+          end
+        end
+
         UPDATER = {
           ::String => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ") },
           ::Symbol => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ").to_sym },
           ::Array => proc { |old_value, new_value| [old_value, new_value] },
-          ::Hash => proc { |old_value, new_value| merge(old_value, new_value.transform_keys(&:to_sym)) }
+          ::Hash => proc { |old_value, new_value| old_value.merge(new_value.transform_keys(&:to_sym)) }
         }.freeze
 
         def update(id, new_value)
@@ -115,18 +193,12 @@ module Sevgi
         private_constant :UPDATER
 
         def to_xml(id, value)
-          case value
-          when ::Hash
-            "#{id}=\"#{value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")}\""
-          when ::Array
-            "#{id}=\"#{value.join(" ")}\""
-          else
-            "#{id}=#{value.to_s.encode(xml: :attr)}"
-          end
+          "#{id}=#{Attribute.xml_text(value).encode(xml: :attr)}"
         end
       end
     end
 
+    # Public alias for the SVG attribute store.
     Attributes = Attribute::Store
   end
 end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Sevgi
+  module Graphics
+    # SVG canvas size, margins, viewport, and viewBox.
+    class Canvas
+      ORIGIN_FIELDS = %i[x y].freeze
+      REPLACEMENTS = %i[width height unit name margins].freeze
+      private_constant :ORIGIN_FIELDS, :REPLACEMENTS
+
+      # @overload call(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 self.call(...) = from_paper(...)
+
+      # 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 self.from_paper(arg = Undefined, **kwargs)
+        case arg
+        when Undefined
+          new(**kwargs)
+        else
+          new(**paper(arg).to_h, **kwargs)
+        end
+      end
+
+      def self.paper(arg)
+        case arg
+        when Paper
+          arg
+        when ::Symbol, ::String
+          ArgumentError.("Unknown paper profile: #{arg}") unless Paper.exist?(arg)
+
+          Paper.public_send(arg)
+        else
+          ArgumentError.("Argument must be a Paper symbol: #{arg}")
+        end
+      end
+
+      private_class_method :paper
+
+      extend Forwardable
+
+      def_delegators :@margin, *Margin.members
+      def_delegators :@size, *Paper.members
+
+      # @!attribute [r] size
+      #   @return [Sevgi::Graphics::Paper] paper size object
+      # @!attribute [r] margin
+      #   @return [Sevgi::Graphics::Margin] canvas margins
+      # @!attribute [r] inner
+      #   @return [Sevgi::Graphics::Paper] inner paper after margins
+      attr_reader :size, :margin, :inner
+
+      # Creates a canvas.
+      # @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 [void]
+      # @raise [Sevgi::ArgumentError] when margins or numeric dimensions are invalid
+      def initialize(width:, height:, unit: "mm", name: :custom, margins: [])
+        @size = Paper[width, height, unit, name]
+        @margin = Margin[*margins]
+
+        compute
+        freeze
+      end
+
+      # @overload attributes(origin = Undefined)
+      #   Returns SVG root viewport attributes.
+      #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
+      #   @return [Hash]
+      #   @raise [Sevgi::ArgumentError] when origin is invalid
+      def attributes(...) = {**viewport, viewBox: viewbox(...)}
+
+      # Returns SVG width and height attributes.
+      # @return [Hash]
+      def viewport = {width: "#{width}#{unit}", height: "#{height}#{unit}"}
+
+      # Returns the SVG viewBox string.
+      # @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
+      # @return [String]
+      # @raise [Sevgi::ArgumentError] when origin is invalid
+      def viewbox(origin = Undefined) = prettify(*originate(origin), width, height).join(" ")
+
+      # Returns a canvas with selected fields replaced.
+      # @param kwargs [Hash] replacement options
+      # @option kwargs [Numeric] :width replacement canvas width
+      # @option kwargs [Numeric] :height replacement canvas height
+      # @option kwargs [Symbol, String] :unit replacement SVG unit
+      # @option kwargs [Symbol, String] :name replacement paper name
+      # @option kwargs [Array<Numeric>] :margins replacement margin shorthand values
+      # @return [Sevgi::Graphics::Canvas]
+      # @raise [Sevgi::ArgumentError] when an unknown option is supplied
+      # @raise [Sevgi::ArgumentError] when a replacement value is invalid
+      def with(**kwargs)
+        unknown = kwargs.keys - REPLACEMENTS
+
+        ArgumentError.("Unknown canvas option: #{unknown.first}") unless unknown.empty?
+
+        margins = kwargs.fetch(:margins, margin.to_a)
+        replacements = kwargs.dup.tap { it.delete(:margins) }
+
+        self.class.new(**size.to_h, **replacements, margins:)
+      end
+
+      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 coordinate!(field, value)
+        Float(value)
+      rescue ::ArgumentError, ::TypeError
+        ArgumentError.("Invalid canvas origin #{field}: #{value.inspect}")
+      end
+
+      def prettify(*floats)
+        floats.map { (it % 1).zero? ? it.to_i : it }
+      end
+
+      def pair(array)
+        ArgumentError.("Canvas origin must have exactly two coordinates") unless array.size == 2
+
+        ORIGIN_FIELDS.zip(array).map { |field, value| coordinate!(field, value) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Renderable text-like content inside an SVG element.
+    class Content
+      # @!attribute [r] content
+      #   @return [Object] wrapped content
+      attr_reader :content
+
+      # Creates content.
+      # @param content [Object] wrapped content
+      # @return [void]
+      def initialize(content) = @content = content
+
+      # Renders content with a renderer.
+      # @abstract Subclasses implement content rendering.
+      # @param _renderer [Object] renderer receiving output
+      # @param _depth [Integer] current render depth
+      # @return [void]
+      # @raise [Sevgi::PanicError] when a subclass does not implement render
+      def render(_renderer, _depth) = PanicError.("#{self.class}#render must be implemented")
+
+      # Returns content as a string.
+      # @return [String]
+      def to_s = content.to_s
+
+      # @overload cdata(content)
+      #   Builds CDATA content.
+      #   Content values are stringified during rendering, and embedded CDATA terminators are split safely.
+      #   @param content [Object] wrapped content
+      #   @return [Sevgi::Graphics::Content::CData]
+      def self.cdata(...) = CData.new(...)
+
+      # Wraps content arguments, encoding non-content values.
+      # Non-content values are stringified by encoded content before XML text escaping.
+      # @param args [Array<Object>] content arguments
+      # @return [Array<Sevgi::Graphics::Content>]
+      def self.contents(*args) = args.map { it.is_a?(Content) ? it : encoded(it) }
+
+      # @overload css(content)
+      #   Builds CSS content.
+      #   @param content [Hash] CSS rules
+      #   @return [Sevgi::Graphics::Content::CSS]
+      #   @raise [Sevgi::ArgumentError] when content is not a hash
+      def self.css(...) = CSS.new(...)
+
+      # @overload encoded(content)
+      #   Builds XML text-encoded content.
+      #   Arbitrary objects are stringified before XML text escaping.
+      #   @param content [Object] wrapped content
+      #   @return [Sevgi::Graphics::Content::Encoded]
+      def self.encoded(...) = Encoded.new(...)
+
+      # Joins content lines with newlines.
+      # @param contents [Object, Array<Object>] content lines
+      # @return [String]
+      def self.text(contents) = Array(contents).join("\n")
+
+      # @overload verbatim(content)
+      #   Builds verbatim content.
+      #   @param content [Object] wrapped content
+      #   @return [Sevgi::Graphics::Content::Verbatim]
+      def self.verbatim(...) = Verbatim.new(...)
+
+      # CDATA section content.
+      class CData < Content
+        TERMINATOR = "]]>"
+        TERMINATOR_SPLIT = "]]]]><![CDATA[>"
+        private_constant :TERMINATOR, :TERMINATOR_SPLIT
+
+        # Renders CDATA content.
+        # Embedded `]]>` terminators are split across adjacent CDATA sections so the output remains valid XML.
+        # @param renderer [Object] renderer receiving output
+        # @param depth [Integer] current render depth
+        # @return [void]
+        def render(renderer, depth)
+          depth += 1
+
+          renderer.append(depth, "<![CDATA[")
+          renderer.append(depth + 1, *Array(content).map { safe(it) })
+          renderer.append(depth, "]]>")
+        end
+
+        private
+
+        def safe(value) = value.to_s.gsub(TERMINATOR, TERMINATOR_SPLIT)
+      end
+
+      # CSS content rendered inside a CDATA section.
+      class CSS < Content
+        # Creates CSS content.
+        # @param content [Hash] CSS rules
+        # @return [void]
+        # @raise [Sevgi::ArgumentError] when content is not a hash
+        def initialize(content)
+          ArgumentError.("CSS content must be a hash: #{content}") unless content.is_a?(::Hash)
+
+          super
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        # Renders CSS content.
+        # @param renderer [Object] renderer receiving output
+        # @param depth [Integer] current render depth
+        # @return [void]
+        # @raise [Sevgi::ArgumentError] when a style value cannot be rendered
+        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
+
+      # XML text-encoded content.
+      class Encoded < Content
+        # Returns XML text-encoded content.
+        # @return [String]
+        def to_s = content.to_s.encode(xml: :text)
+
+        # Renders encoded text content.
+        # @param renderer [Object] renderer receiving output
+        # @param depth [Integer] current render depth
+        # @return [void]
+        def render(renderer, depth) = renderer.append(depth + 1, to_s)
+      end
+
+      # Verbatim content rendered without XML text encoding.
+      class Verbatim < Content
+        # Renders verbatim content.
+        # @param renderer [Object] renderer receiving output
+        # @param depth [Integer] current render depth
+        # @return [void]
+        def render(renderer, depth) = renderer.append(depth + 1, to_s)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Four-sided margin with CSS-like shorthand normalization.
+    Margin = Data.define(:top, :right, :bottom, :left) do
+      include Comparable
+
+      # @!attribute [r] top
+      #   @return [Float] top margin
+      # @!attribute [r] right
+      #   @return [Float] right margin
+      # @!attribute [r] bottom
+      #   @return [Float] bottom margin
+      # @!attribute [r] left
+      #   @return [Float] left margin
+
+      # Creates a margin from one to four shorthand values.
+      # @param top [Numeric, nil] top value or all-sides shorthand
+      # @param right [Numeric, nil] right value or horizontal shorthand
+      # @param bottom [Numeric, nil] bottom value
+      # @param left [Numeric, nil] left value
+      # @return [void]
+      def initialize(top: nil, right: nil, bottom: nil, left: nil)
+        super(**normalize(top, right, bottom, left))
+      end
+
+      # Compares margins by top, right, bottom, then left.
+      # @param other [Sevgi::Graphics::Margin] margin to compare
+      # @return [Integer, nil]
+      def <=>(other) = deconstruct <=> other.deconstruct
+
+      # Returns a margin inflated horizontally and vertically.
+      # @param h [Numeric] horizontal addition
+      # @param v [Numeric] vertical addition
+      # @return [Sevgi::Graphics::Margin]
+      def adjust(h, v) = self.class[top + v, right + h, bottom + v, left + h]
+
+      # Reports strict margin equality.
+      # @param other [Object] object to compare
+      # @return [Boolean]
+      def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
+
+      # Returns a hash compatible with strict equality.
+      # @return [Integer]
+      def hash = [self.class, *deconstruct].hash
+
+      # Returns total horizontal margin.
+      # @return [Float]
+      def horizontal = left + right
+
+      # Returns total vertical margin.
+      # @return [Float]
+      def vertical = top + bottom
+
+      alias_method :==, :eql?
+      alias_method :to_a, :deconstruct
+
+      # Builds a margin from an array-like shorthand.
+      # @param array [Object] value converted with Array()
+      # @return [Sevgi::Graphics::Margin]
+      def self.margin(array)
+        self[
+          *(array = Array(array)[0...(size = Margin.members.size)]).fill(nil, array.size, size - array.size)
+        ]
+      end
+
+      # Returns a zero margin.
+      # @return [Sevgi::Graphics::Margin]
+      def self.zero = (@zero ||= self[0.0, 0.0, 0.0, 0.0])
+
+      private
+
+      def normalize(top, right, bottom, left)
+        values = [top, right, bottom, left]
+
+        Margin.members.zip(values_for(values.compact.size, values).map { Float(it) }).to_h
+      end
+
+      def values_for(size, values)
+        top, right, bottom = values
+
+        [
+          [0, 0, 0, 0],
+          [top, top, top, top],
+          [top, right, top, right],
+          [top, right, bottom, right]
+        ][size] ||
+          values
+      end
+    end
+  end
+end