sevgi-graphics 0.94.0 → 0.95.0

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

@@ -9,6 +9,9 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] defs attributes
+        # @yield [name] converts each callable name to a symbol id
+        # @yieldparam name [Symbol] callable method name
+        # @yieldreturn [String, Symbol] symbol id
         # @return [Sevgi::Graphics::Element] defs element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Symbols(mod, *args, **kwargs, &block)

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

@@ -18,6 +18,8 @@ module Sevgi
         # @param dy [Numeric] vertical spacing
         # @param oy [Numeric] vertical offset
         # @param proc [Proc, nil] optional coordinate/customization proc
+        # @yield evaluates the template drawing DSL in a generated group
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def Tile(
@@ -67,6 +69,8 @@ module Sevgi
         # @param d [Numeric] horizontal spacing
         # @param o [Numeric] horizontal offset
         # @param proc [Proc, nil] optional coordinate/customization proc
+        # @yield evaluates the template drawing DSL in a generated group
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileX(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
@@ -100,6 +104,8 @@ module Sevgi
         # @param d [Numeric] vertical spacing
         # @param o [Numeric] vertical offset
         # @param proc [Proc, nil] optional coordinate/customization proc
+        # @yield evaluates the template drawing DSL in a generated group
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileY(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)

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

@@ -15,9 +15,9 @@ module Sevgi
         # 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
+        # @raise [Sevgi::ArgumentError] when comment cannot be stringified as valid XML or would form malformed markup
         def Comment(comment)
-          comment = comment.to_s
+          comment = XML.text(comment, context: "XML comment")
 
           ArgumentError.("XML comment must not contain '--'") if comment.include?("--")
           ArgumentError.("XML comment must not end with '-'") if comment.end_with?("-")

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

@@ -4,6 +4,18 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for SVG standard validation.
+      #
+      # @!method CData
+      #   Returns text content used as SVG character data.
+      #   @return [String, nil] joined text content or nil
+      # @!method NS?(name)
+      #   Reports whether a namespace is available on this element or an ancestor.
+      #   @param name [Symbol, String] namespace suffix without xmlns:
+      #   @return [Boolean]
+      # @!method Validate
+      #   Validates this subtree against SVG standard metadata when that component is available.
+      #   @return [Sevgi::Graphics::Element, nil] self after validation, or nil without sevgi/standard
+      #   @raise [Sevgi::ValidationError] when SVG validation fails
       module Validate
         # Returns text content used as SVG character data.
         # @return [String, nil] joined text content or nil

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

@@ -27,6 +27,8 @@ module Sevgi
         # Builds a titled SVG symbol.
         # @param name [String] human-readable symbol name
         # @param kwargs [Hash] symbol attributes
+        # @yield evaluates the drawing DSL in the symbol element
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] symbol element
         def Symbol(name, **kwargs, &block)
           id = (words = name.split).map(&:downcase).join("-")
@@ -63,7 +65,8 @@ module Sevgi
         # @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
+        # @raise [Sevgi::ArgumentError] when CSS rules are malformed, cyclic, cannot be stringified, or contain invalid
+        #   encoding or illegal XML 1.0 characters
         def css(hash = nil, **attributes)
           hash, attributes = attributes, {} unless hash
 

data/lib/sevgi/graphics/mixtures.rb

@@ -8,11 +8,15 @@ module Sevgi
       #   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
+      #   @yield defines methods in the anonymous mixture
+      #   @yieldreturn [Object] ignored module-definition result
       #   @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
+      #   @yield defines methods in the anonymous mixture
+      #   @yieldreturn [Object] ignored module-definition result
       #   @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)

data/lib/sevgi/graphics/version.rb

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

data/lib/sevgi/graphics/xml.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # XML 1.0 text and qualified-name validation shared by renderer boundaries.
+    # @api private
+    module XML
+      NCNAME_START = "A-Z_a-z\u{C0}-\u{D6}\u{D8}-\u{F6}\u{F8}-\u{2FF}\u{370}-\u{37D}\u{37F}-\u{1FFF}" \
+        "\u{200C}-\u{200D}\u{2070}-\u{218F}\u{2C00}-\u{2FEF}\u{3001}-\u{D7FF}\u{F900}-\u{FDCF}" \
+        "\u{FDF0}-\u{FFFD}\u{10000}-\u{EFFFF}"
+      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
+
+      private_constant :NCNAME, :NCNAME_CHAR, :NCNAME_START, :QNAME
+
+      class << self
+        # Validates an XML 1.0 string representation.
+        # @param value [Object] value to stringify and validate
+        # @param context [String] error-message subject
+        # @return [String] UTF-8 text
+        # @raise [Sevgi::ArgumentError] when stringification, encoding, or XML character validation fails
+        def text(value, context: "XML content")
+          value = stringify(value, context:) unless value.is_a?(::String)
+          validate_string(value, context:)
+        end
+
+        # Validates and snapshots a nested XML-bound value.
+        # @param value [Object] scalar or nested container
+        # @param context [String] error-message subject
+        # @param seen [Hash] container identities on the current traversal path
+        # @return [Object] validated caller-owned snapshot
+        # @raise [Sevgi::ArgumentError] when the value is cyclic, collides after stringification, or has invalid XML text
+        def snapshot(value, context:, seen: {}.compare_by_identity)
+          case value
+          when ::Hash
+            nested(value, context:, seen:) { snapshot_hash(value, context:, seen:) }
+          when ::Array
+            nested(value, context:, seen:) { value.map { snapshot(it, context:, seen:) } }
+          else
+            text(value, context:)
+          end
+        end
+
+        # Validates an XML qualified name.
+        # @param value [Object] candidate name
+        # @param context [String] error-message subject
+        # @return [String] validated qualified name
+        # @raise [Sevgi::ArgumentError] when text conversion or QName validation fails
+        def name(value, context: "XML name")
+          text(value, context:).tap do |candidate|
+            ArgumentError.("#{context} is invalid: #{candidate.inspect}") unless QNAME.match?(candidate)
+          end
+        end
+
+        # Validates a nested XML value without retaining its snapshot.
+        # @param value [Object] scalar or nested container
+        # @param context [String] error-message subject
+        # @return [Object] original value
+        # @raise [Sevgi::ArgumentError] when nested content is cyclic or contains invalid XML text
+        def validate(value, context: "XML content")
+          snapshot(value, context:)
+          value
+        end
+
+        # Escapes embedded CDATA terminators after validating text.
+        # @param value [Object] CDATA value
+        # @return [String] safe CDATA body
+        # @raise [Sevgi::ArgumentError] when value is not valid XML text
+        def cdata(value) = text(value).gsub("]]>", "]]]]><![CDATA[>")
+
+        private
+
+        def nested(value, context:, seen:)
+          ArgumentError.("Cyclic #{context} is not supported") if seen.key?(value)
+
+          seen[value] = true
+          yield
+        ensure
+          seen.delete(value)
+        end
+
+        def snapshot_hash(value, context:, seen:)
+          value.each_with_object({}) do |(key, item), captured|
+            key = snapshot(key, context:, seen:)
+            ArgumentError.("#{context} keys collide after stringification") if captured.key?(key)
+
+            captured[key] = snapshot(item, context:, seen:)
+          end
+        end
+
+        def stringify(value, context:)
+          text = value.to_s
+          ArgumentError.("#{context} stringification must return a String") unless text.is_a?(::String)
+
+          text
+        rescue Sevgi::ArgumentError
+          raise
+        rescue ::StandardError => e
+          ArgumentError.("#{context} cannot be stringified: #{e.class}: #{e.message}")
+        end
+
+        def validate_string(value, context:)
+          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)}")
+          end
+
+          text
+        rescue ::EncodingError => e
+          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
+
+    private_constant :XML
+  end
+end

data/lib/sevgi/graphics.rb

@@ -2,6 +2,7 @@
 
 require "sevgi/function"
 
+require_relative "graphics/xml"
 require_relative "graphics/attribute"
 require_relative "graphics/auxiliary"
 require_relative "graphics/element"
@@ -30,35 +31,40 @@ module Sevgi
     #   @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.
+    #   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.
     #   @param name [Symbol, String] profile name
     #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
-    #   @param attributes [Hash, Sevgi::Undefined] default root attributes
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
     #   @return [Class] document class
-    #   @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
+    #   @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, Sevgi::Undefined] default root attributes
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
     #   @return [Class] anonymous document class
-    #   @raise [Sevgi::ArgumentError] when profile input is invalid
+    #   @raise [Sevgi::ArgumentError] when metadata is invalid XML, cyclic, or cannot be stringified
     # @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.
+    # Validation and snapshot capture complete before an existing registration is atomically replaced.
     # @param name [Symbol, String] profile name
     # @param preambles [Array<String>, nil] document preamble lines
-    # @param attributes [Hash] default root attributes
+    # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
     # @return [Class] document class
-    # @raise [Sevgi::ArgumentError] when the profile name is invalid
+    # @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.
+    # 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.
     # @param width [Numeric] paper width
     # @param height [Numeric] paper height
     # @param name [Symbol, String] profile name
@@ -66,13 +72,7 @@ module Sevgi
     # @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")
-      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
+      Graphics::Paper.define(name, width:, height:, unit:, overwrite: false)
 
       name
     end
@@ -91,9 +91,10 @@ module Sevgi
     # 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
+    # @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 or canvas profile is unknown
+    # @raise [Sevgi::ArgumentError] when the document/canvas profile or root XML attributes are invalid
     def SVG(document = :default, canvas = Undefined, **, &block)
       Graphics::Document.(document, canvas, **, &block)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-graphics
 version: !ruby/object:Gem::Version
-  version: 0.94.0
+  version: 0.95.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.94.0
+        version: 0.95.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.94.0
+        version: 0.95.0
 description: Provides an extensible DSL for creating SVG content.
 email: roktas@gmail.com
 executables: []
@@ -39,6 +39,8 @@ files:
 - lib/sevgi/graphics/auxiliary/content.rb
 - lib/sevgi/graphics/auxiliary/margin.rb
 - lib/sevgi/graphics/auxiliary/paper.rb
+- lib/sevgi/graphics/auxiliary/scalar.rb
+- lib/sevgi/graphics/auxiliary/sizes.rb
 - lib/sevgi/graphics/document.rb
 - lib/sevgi/graphics/document/base.rb
 - lib/sevgi/graphics/document/default.rb
@@ -67,6 +69,7 @@ files:
 - lib/sevgi/graphics/mixtures/validate.rb
 - lib/sevgi/graphics/mixtures/wrappers.rb
 - lib/sevgi/graphics/version.rb
+- lib/sevgi/graphics/xml.rb
 homepage: https://sevgi.roktas.dev
 licenses:
 - GPL-3.0-or-later
@@ -89,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Core DSL for the Sevgi toolkit.
 test_files: []