sevgi-standard 0.93.1 → 0.95.0

data/README.md

@@ -1,5 +1,37 @@
 # Sevgi Standard
 
-Provides SVG element, attribute, and conformance data used by Sevgi validation.
+SVG element, attribute, and conformance data used by Sevgi validation.
 
-See the root [README](../README.md) and the documentation site for usage.
+## Install
+
+```sh
+gem install sevgi-standard
+```
+
+## Require
+
+```ruby
+require "sevgi/standard"
+```
+
+## Example
+
+```ruby
+Sevgi::Standard.element?(:rect)
+Sevgi::Standard.attribute?(:width)
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 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-standard
+- Source: https://github.com/roktas/sevgi/tree/main/standard
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/standard/conform.rb

@@ -14,11 +14,14 @@ module Sevgi
       attr_reader :spec
 
       # Builds a validator for one SVG element.
-      # @param element [Symbol] SVG element name
+      # @param element [String, Symbol] SVG element name
       # @return [void]
+      # @raise [Sevgi::ArgumentError] when element is not a valid public name
       # @raise [Sevgi::InvalidElementsError] when the element is unknown
       # @raise [Sevgi::PanicError] when the element model is missing or unimplemented
       def initialize(element)
+        element = Name.normalize!(element, context: "element")
+
         InvalidElementsError.(element) unless (@spec = Specification[@element = element])
 
         PanicError.("No model specified: #{element}") unless spec[:model]
@@ -30,10 +33,11 @@ module Sevgi
       end
 
       # Validates one usage of the configured SVG element.
-      # @param attributes [Array<Symbol>, nil] attribute names used by the element
+      # @param attributes [Array<String, Symbol>, String, Symbol, nil] attribute names used by the element
       # @param cdata [String, nil] character data content
-      # @param elements [Array<Symbol>, nil] child element names
+      # @param elements [Array<String, Symbol>, String, Symbol, nil] child element names
       # @return [Boolean] true when the usage conforms
+      # @raise [Sevgi::ArgumentError] when any name is not a valid public name
       # @raise [Sevgi::ValidationError] when the usage violates the standard data
       def call(attributes: nil, cdata: nil, elements: nil)
         if attributes
@@ -50,21 +54,39 @@ module Sevgi
       @cache = {}
 
       # Validates one SVG element usage, using cached element validators.
-      # @param element [Symbol] SVG element name
-      # @param attributes [Array<Symbol>, nil] attribute names used by the element
+      # @param element [String, Symbol] SVG element name
+      # @param attributes [Array<String, Symbol>, nil] attribute names used by the element
       # @param cdata [String, nil] character data content
-      # @param elements [Array<Symbol>, nil] child element names
+      # @param elements [Array<String, Symbol>, nil] child element names
       # @return [Boolean] true when the usage conforms or the element is ignored
+      # @raise [Sevgi::ArgumentError] when any name is not a valid public name
       # @raise [Sevgi::ValidationError] when the usage violates the standard data
       # @raise [Sevgi::PanicError] when the standard data refers to an invalid model
       def self.call(element, attributes: nil, cdata: nil, elements: nil)
+        element = Name.normalize!(element, context: "element")
+        attributes = Name.list!(attributes, context: "attribute")
+        elements = Name.list!(elements, context: "element") || []
+
         Element.ignore?(element) or
-          (@cache[element] ||= new(element)).call(
-            attributes: Attribute.concerns(attributes),
-            elements: Element.concerns(elements || []),
-            cdata:
-          )
+          validate(element, attributes:, elements:, cdata:)
+      end
+
+      def self.validate(element, attributes:, elements:, cdata:)
+        validator = @cache[element] || new(element)
+        result = validator.call(**arguments(attributes, elements, cdata))
+        @cache[element] ||= validator
+        result
       end
+
+      def self.arguments(attributes, elements, cdata)
+        {
+          attributes: Attribute.concerns(attributes),
+          elements: Element.concerns(elements),
+          cdata:
+        }
+      end
+
+      private_class_method :arguments, :validate
     end
 
     private_constant :Conform, :Model

data/lib/sevgi/standard/data/attribute.rb

@@ -483,7 +483,6 @@ module Sevgi
         Deprecated: %i[
           accent-height
           alphabetic
-          amplitude
           arabic-form
           ascent
           attributeType
@@ -492,12 +491,29 @@ module Sevgi
         ]
       )
 
+      RESERVED_NAMESPACE_PREFIXES = %w[xlink: xml:].freeze
+      private_constant :RESERVED_NAMESPACE_PREFIXES
+
+      # Reports whether an attribute name should be ignored by standard validation.
+      # @param attribute [String, Symbol, Object] candidate attribute name
+      # @return [Boolean] true for valid private, data, xmlns, or foreign namespaced attributes
       def ignore?(attribute)
-        attribute.start_with?("_") ||
-          attribute == :xmlns ||
-          attribute.start_with?("data-") ||
-          (attribute.to_s.include?(":") && !attribute.start_with?("xlink:") && !attribute.start_with?("xml:"))
+        return false unless attribute.is_a?(::String) || attribute.is_a?(::Symbol)
+
+        name = attribute.to_s
+
+        Name.valid?(name) && ignored_name?(name)
       end
+
+      def ignored_name?(name)
+        name.start_with?("_") || name == "xmlns" || name.start_with?("data-") || foreign_namespace?(name)
+      end
+
+      def foreign_namespace?(name)
+        name.include?(":") && RESERVED_NAMESPACE_PREFIXES.none? { name.start_with?(it) }
+      end
+
+      private_class_method :foreign_namespace?, :ignored_name?
     end
   end
 end

data/lib/sevgi/standard/data/element.rb

@@ -8,6 +8,7 @@ module Sevgi
           animate
           animateMotion
           animateTransform
+          discard
           mpath
           set
         ],
@@ -146,7 +147,6 @@ module Sevgi
           linearGradient
           pattern
           radialGradient
-          solidcolor
         ],
 
         Renderable: %i[
@@ -265,8 +265,15 @@ module Sevgi
         ]
       )
 
+      # Reports whether an element name should be ignored by standard validation.
+      # @param element [String, Symbol, Object] candidate element name
+      # @return [Boolean] true for valid private or namespaced element names that Sevgi should not validate
       def ignore?(element)
-        (name = element.to_s).include?(":") || name.start_with?("_")
+        return false unless element.is_a?(::String) || element.is_a?(::Symbol)
+
+        name = element.to_s
+
+        Name.valid?(name) && (name.include?(":") || name.start_with?("_"))
       end
     end
   end

data/lib/sevgi/standard/data.rb

@@ -4,12 +4,44 @@ require_relative "data/color"
 
 module Sevgi
   module Standard
+    # Defensive copy helper for public standard-data snapshots.
+    # @api private
+    module Snapshot
+      # Returns a recursively independent copy of a value.
+      # @param value [Object] value to copy
+      # @return [Object] copied value
+      def self.copy(value)
+        case value
+        when ::Hash
+          hash(value)
+        when ::Array
+          value.map { copy(it) }
+        when ::Set
+          Set[*value.map { copy(it) }]
+        else
+          duplicate(value)
+        end
+      end
+
+      def self.hash(value) = value.to_h { |key, item| [key, copy(item)] }
+
+      def self.duplicate(value)
+        value.dup
+      rescue ::TypeError
+        value
+      end
+
+      private_class_method :duplicate, :hash
+    end
+
+    private_constant :Snapshot
+
     # Shared set operations for SVG standard data lists.
     # @api private
     module Common
       # Returns every known name in this data list.
-      # @return [Set<Symbol>]
-      def all = @all ||= Set[*data.values.flatten.uniq.sort]
+      # @return [Set<Symbol>] mutation-isolated set snapshot
+      def all = Snapshot.copy(@all ||= Set[*data.values.flatten.uniq.sort])
 
       # Checks whether a name belongs to a group.
       # @param name [Symbol] item name
@@ -24,9 +56,13 @@ module Sevgi
       def pick(names, *groups) = names.select { |name| groups.any? { is?(name, it) } }
 
       # Returns all names or names from selected groups.
-      # @param groups [Array<Symbol>] group names
-      # @return [Set<Symbol>] selected names
-      def set(*groups) = groups.empty? ? all : Set[*data.values_at(*groups).flatten.compact.uniq.sort]
+      # @param groups [Array<String, Symbol>] group names
+      # @return [Set<Symbol>] mutation-isolated selected-name snapshot
+      def set(*groups)
+        return all if groups.empty?
+
+        Set[*data.values_at(*groups!(groups)).flatten.uniq.sort]
+      end
 
       # Removes names that belong to any requested group.
       # @param names [Array<Symbol>] names to filter
@@ -34,6 +70,16 @@ module Sevgi
       # @return [Array<Symbol>] filtered names
       def unpick(names, *groups) = names.reject { |name| groups.any? { is?(name, it) } }
 
+      def groups!(groups)
+        groups = groups.map { Name.normalize!(it, context: "group") }
+        unknown = groups.reject { data.key?(it) }
+        ArgumentError.("Unknown SVG group(s): #{unknown.map(&:inspect).join(", ")}") unless unknown.empty?
+
+        groups
+      end
+
+      private :groups!
+
       # Removes ignored names from a list.
       # @param names [Array<Symbol>, nil] names to filter
       # @return [Array<Symbol>, nil] names that should be validated
@@ -74,8 +120,8 @@ module Sevgi
 
       # Returns expanded standard specification data for one element.
       # @param name [Symbol] SVG element name
-      # @return [Hash, nil] expanded specification data
-      def [](name) = expand(name)
+      # @return [Hash, nil] mutation-isolated expanded specification snapshot
+      def [](name) = Snapshot.copy(expand(name))
 
       # Reports whether a name is a data group name.
       # @param name [Symbol] element or group name
@@ -83,33 +129,42 @@ module Sevgi
       def group?(name) = /[[:upper:]]/.match?(name[0])
 
       # Checks whether an element uses one of the requested content models.
-      # @param name [Symbol] SVG element name
-      # @param models [Array<Symbol>] model names to match
+      # @param name [String, Symbol] SVG element name
+      # @param models [Array<String, Symbol>] model names to match
       # @return [Boolean]
-      def model?(name, *models) = models.any? { (self[name] || {})[:model] == it }
+      # @raise [Sevgi::ArgumentError] when any name is not a valid public name
+      def model?(name, *models)
+        name = Name.normalize!(name, context: "element")
+        models = models.map { Name.normalize!(it, context: "model") }
+
+        models.any? { (self[name] || {})[:model] == it }
+      end
 
       private
 
       @spec = {}
 
       def expand(name)
-        @spec[name] ||= if data[name]
-          data[name].transform_values { |value| value.is_a?(::Array) ? value.dup : value }.tap do |spec|
-            expand_names(spec[:elements], Element.data)
-            expand_names(spec[:attributes], Attribute.data)
+        return unless data.key?(name)
+
+        @spec[name] ||= data
+          .fetch(name)
+          .transform_values { |value| value.is_a?(::Array) ? value.dup : value }
+          .tap do |spec|
+            expand_names(spec[:elements], Element.send(:data))
+            expand_names(spec[:attributes], Attribute.send(:data))
           end
-        end
       end
 
       def expand_names(names, list)
         return unless names
 
-        names.replace(names.map { |name| group?(name) ? list[name] : name }.flatten)
+        names.replace(names.flat_map { |name| group?(name) ? list[name] : name }.uniq)
       end
 
       # For testing purposes
 
-      def charge = data.keys { expand(it) }
+      def charge = data.each_key { expand(it) }
 
       def flush = (@spec = {})
     end

data/lib/sevgi/standard/internal.rb

@@ -2,6 +2,50 @@
 
 module Sevgi
   module Standard
+    # Normalizes public SVG standard names at API boundaries.
+    # @api private
+    module Name
+      PATTERN = /\A[A-Za-z_][A-Za-z0-9_.-]*(?::[A-Za-z_][A-Za-z0-9_.-]*)?\z/
+      private_constant :PATTERN
+
+      # Reports whether a string is a supported SVG-style name token.
+      # @param name [String] candidate name
+      # @return [Boolean]
+      def self.valid?(name) = !!PATTERN.match?(name)
+
+      # Normalizes one public name to the registry symbol form.
+      # @param value [String, Symbol] public name
+      # @param context [String] name context for error messages
+      # @return [Symbol] normalized name
+      # @raise [Sevgi::ArgumentError] when value is not a String or Symbol
+      # @raise [Sevgi::ArgumentError] when value is not a valid SVG-style name
+      def self.normalize!(value, context:)
+        case value
+        when ::String, ::Symbol
+          text = value.to_s
+          ArgumentError.("Invalid SVG #{context} name: #{value.inspect}") unless valid?(text)
+
+          text.to_sym
+        else
+          ArgumentError.("SVG #{context} name must be a String or Symbol: #{value.inspect}")
+        end
+      end
+
+      # Normalizes a list of public names.
+      # @param values [Array<String, Symbol>, String, Symbol, nil] public names
+      # @param context [String] name context for error messages
+      # @return [Array<Symbol>, nil] normalized names
+      # @raise [Sevgi::ArgumentError] when any value is not a valid public name
+      def self.list!(values, context:)
+        return if values.nil?
+
+        values = [values] unless values.is_a?(::Array)
+        values.map { normalize!(it, context:) }
+      end
+    end
+
+    private_constant :Name
+
     # Low-level import and lookup helper for static SVG standard data.
     # @api private
     module List
@@ -32,6 +76,7 @@ module Sevgi
 
           class << self
             attr_reader :data
+            private :data
           end
         end
       end

data/lib/sevgi/standard/model.rb

@@ -103,7 +103,7 @@ module Sevgi
             UnmetConditionError.(element, "Exactly one FilterLightSource element as first required")
           end
 
-          if !(unallowed = Element.unpick(elements[1..], :Descriptive)).empty? && !unallowed.empty?
+          unless (unallowed = Element.unpick(elements[1..], :Descriptive)).empty?
             UnallowedElementsError.(element, unallowed)
           end
         end

data/lib/sevgi/standard/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Standard
     # Current version of the Sevgi standard gem.
-    VERSION = "0.93.1"
+    VERSION = "0.95.0"
   end
 end

data/lib/sevgi/standard.rb

@@ -12,53 +12,67 @@ require_relative "standard/version"
 
 module Sevgi
   # SVG standard data and validation helpers.
+  # The registry is a Sevgi compatibility set based on SVG 2 plus the split-out SVG modules and legacy entries already
+  # modeled in the bundled specifications. Supported element names must have matching specification data; abandoned or
+  # unspecified proposal entries are not exposed as supported elements.
   module Standard
     extend self
 
     # @overload attributes(*groups)
     #   Returns SVG attributes, optionally restricted to one or more attribute groups.
-    #   @param groups [Array<Symbol>] attribute group names
-    #   @return [Set<Symbol>] attribute names
+    #   @param groups [Array<String, Symbol>] attribute group names
+    #   @return [Set<Symbol>] mutation-isolated attribute-name snapshot
     def attributes(...) = Attribute.set(...)
 
     # Reports whether an attribute name is recognized by the SVG standard data.
-    # @param name [Object] attribute name
+    # @param name [String, Symbol] attribute name
     # @return [Boolean]
-    def attribute?(name) = name.respond_to?(:to_sym) && Attribute.all.include?(name.to_sym)
+    # @raise [Sevgi::ArgumentError] when name is not a String or Symbol
+    # @raise [Sevgi::ArgumentError] when name is not a valid SVG-style name
+    def attribute?(name) = Attribute.all.include?(Name.normalize!(name, context: "attribute"))
 
     # @overload conform(element, attributes: nil, cdata: nil, elements: nil)
     #   Validates an SVG element usage against the standard data.
-    #   @param element [Symbol] SVG element name
-    #   @param attributes [Array<Symbol>, nil] attribute names used by the element
+    #   @param element [String, Symbol] SVG element name
+    #   @param attributes [Array<String, Symbol>, String, Symbol, nil] attribute names used by the element
     #   @param cdata [String, nil] character data content
-    #   @param elements [Array<Symbol>, nil] child element names
+    #   @param elements [Array<String, Symbol>, String, Symbol, nil] child element names
     #   @return [Boolean] true when the usage conforms
+    #   @raise [Sevgi::ArgumentError] when any name is not a String or Symbol
+    #   @raise [Sevgi::ArgumentError] when any name is not a valid SVG-style name
     #   @raise [Sevgi::ValidationError] when the usage violates the standard data
     #   @raise [Sevgi::PanicError] when the standard data refers to an invalid model
     def conform(...) = Conform.(...)
 
     # @overload elements(*groups)
     #   Returns SVG elements, optionally restricted to one or more element groups.
-    #   @param groups [Array<Symbol>] element group names
-    #   @return [Set<Symbol>] element names
+    #   @param groups [Array<String, Symbol>] element group names
+    #   @return [Set<Symbol>] mutation-isolated element-name snapshot
     def elements(...) = Element.set(...)
 
     # Reports whether an element name is recognized by the SVG standard data.
-    # @param name [Object] element name
+    # @param name [String, Symbol] element name
     # @return [Boolean]
-    def element?(name) = name.respond_to?(:to_sym) && Element.all.include?(name.to_sym)
+    # @raise [Sevgi::ArgumentError] when name is not a String or Symbol
+    # @raise [Sevgi::ArgumentError] when name is not a valid SVG-style name
+    def element?(name) = Element.all.include?(Name.normalize!(name, context: "element"))
 
     # @overload model?(name, *models)
     #   Checks whether an element uses one of the requested content models.
-    #   @param name [Symbol] SVG element name
-    #   @param models [Array<Symbol>] model names to match
+    #   @param name [String, Symbol] SVG element name
+    #   @param models [Array<String, Symbol>] model names to match
     #   @return [Boolean]
+    #   @raise [Sevgi::ArgumentError] when any name is not a String or Symbol
+    #   @raise [Sevgi::ArgumentError] when any name is not a valid SVG-style name
     def model?(...) = Specification.model?(...)
 
     # Returns the expanded standard contract for an SVG element.
-    # @param name [Object] SVG element name
-    # @return [Hash, nil] expanded specification data, or nil when name is invalid or unknown
-    def specification(name) = name.respond_to?(:to_sym) ? Specification[name.to_sym] : nil
+    # The returned hash and nested arrays are mutation-isolated snapshots; changing them does not alter the registry.
+    # @param name [String, Symbol] SVG element name
+    # @return [Hash, nil] expanded specification snapshot, or nil when name is unknown
+    # @raise [Sevgi::ArgumentError] when name is not a String or Symbol
+    # @raise [Sevgi::ArgumentError] when name is not a valid SVG-style name
+    def specification(name) = Specification[Name.normalize!(name, context: "element")]
 
     alias [] specification
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-standard
 version: !ruby/object:Gem::Version
-  version: 0.93.1
+  version: 0.95.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,20 +15,22 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.95.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.95.0
 description: Validates elements and attributes according to the SVG specification.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sevgi/standard.rb
 - lib/sevgi/standard/conform.rb
@@ -56,14 +58,14 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.11
 specification_version: 4
 summary: SVG Validation for the Sevgi toolkit.
 test_files: []