sevgi-standard 0.73.2 → 0.93.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd86945f53c28030148a5d7e40a05c370ea9743f92cf1c264f3c30741d65baa8
-  data.tar.gz: d4012c0190f449a989c10f35d60153c397dabd9536d5567caa3956c1e3f0db68
+  metadata.gz: 845a552c81846d5e0183f1ef2243ea0ddcf90a94a8bcbe64edab77df9e6ac877
+  data.tar.gz: dd99636019944aaee3d6481c44fc67b48c834718a1f843afd22bfb5c1553ec78
 SHA512:
-  metadata.gz: 65a9c7367b4ebc2e34fe647d71cfe50ee0038ab3acdf688a2e5460d9bd500677ca93c91daa63c08e1b958c6a6b993e864cca65ef0ee38c6bd61b78fbb532846f
-  data.tar.gz: 0b787afc81c3edf324bc272c7d25d22ff7a60d05b48fc8708981dc5ae2e8c6587a178b8a35cb9fba6ca2dd2edc4edc889190ded91a488aa47e007d70272a5d8d
+  metadata.gz: d1d2d534bab867b6357bb7623f498d60a82965446c06c0553cc37a63529a8e783024ff65f10422cdd382dec9f19497f1c435965a4e72bfd3afcb2afb0e228afa
+  data.tar.gz: aae602ac61b37d6c4de6549bb2763d02fd3a1c3de3157dc8f6bc831d1a93a0f357a125be55fb221d0acf3a7a9c2480fc3d8965e8f1b0b3dde5cded9fdb39f070

data/README.md

@@ -0,0 +1,5 @@
+# Sevgi Standard
+
+Provides SVG element, attribute, and conformance data used by Sevgi validation.
+
+See the root [README](../README.md) and the documentation site for usage.

data/lib/sevgi/standard/conform.rb

@@ -2,22 +2,39 @@
 
 module Sevgi
   module Standard
+    # Validates one SVG element usage against the standard data.
+    # @api private
     class Conform
       require_relative "model"
 
-      attr_reader :element, :spec
+      # @return [Symbol] SVG element name
+      attr_reader :element
 
+      # @return [Hash] expanded standard specification for the element
+      attr_reader :spec
+
+      # Builds a validator for one SVG element.
+      # @param element [Symbol] SVG element name
+      # @return [void]
+      # @raise [Sevgi::InvalidElementsError] when the element is unknown
+      # @raise [Sevgi::PanicError] when the element model is missing or unimplemented
       def initialize(element)
         InvalidElementsError.(element) unless (@spec = Specification[@element = element])
 
-        raise ModelError, "No model specified: #{element}" unless spec[:model]
-        raise ModelError, "Model unimplemented: #{spec[:model]}" unless Model.const_defined?(spec[:model])
+        PanicError.("No model specified: #{element}") unless spec[:model]
+        PanicError.("Model unimplemented: #{spec[:model]}") unless Model.const_defined?(spec[:model])
 
         extend(Model.const_get(spec[:model]))
 
-        raise NoMethodError, "#{self.class}#apply must be implemented" unless respond_to?(:apply)
+        PanicError.("#{self.class}#apply must be implemented") unless respond_to?(:apply)
       end
 
+      # Validates one usage of the configured SVG element.
+      # @param attributes [Array<Symbol>, nil] attribute names used by the element
+      # @param cdata [String, nil] character data content
+      # @param elements [Array<Symbol>, nil] child element names
+      # @return [Boolean] true when the usage conforms
+      # @raise [Sevgi::ValidationError] when the usage violates the standard data
       def call(attributes: nil, cdata: nil, elements: nil)
         if attributes
           unrecognized = attributes - spec[:attributes]
@@ -32,11 +49,19 @@ 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 cdata [String, nil] character data content
+      # @param elements [Array<Symbol>, nil] child element names
+      # @return [Boolean] true when the usage conforms or the element is ignored
+      # @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.ignore?(element) or
           (@cache[element] ||= new(element)).call(
             attributes: Attribute.concerns(attributes),
-            elements: Element.concerns(elements),
+            elements: Element.concerns(elements || []),
             cdata:
           )
       end

data/lib/sevgi/standard/data/color.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-# Recognized color keyword names: https://www.w3.org/TR/2003/REC-SVG11-20030114/types.html#ColorKeywords
-
 module Sevgi
   module Standard
+    # Recognized SVG color keyword names mapped to hexadecimal RGB values.
     Color = {
       aliceblue: "#F0F8FF",
       antiquewhite: "#FAEBD7",
@@ -154,7 +153,7 @@ module Sevgi
       yellowgreen: "#9ACD32"
     }
       .tap do |color|
-        def color.valid?(name) = key?(name.to_sym)
+        def color.valid?(name) = name.respond_to?(:to_sym) && key?(name.to_sym)
 
         color.each { |name, hex| color.define_singleton_method(name) { hex } }
       end

data/lib/sevgi/standard/data.rb

@@ -4,19 +4,45 @@ require_relative "data/color"
 
 module Sevgi
   module Standard
+    # 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]
 
+      # Checks whether a name belongs to a group.
+      # @param name [Symbol] item name
+      # @param group [Symbol] group name
+      # @return [Boolean]
       def is?(name, group) = self[group].include?(name)
 
+      # Keeps names that belong to any requested group.
+      # @param names [Array<Symbol>] names to filter
+      # @param groups [Array<Symbol>] group names
+      # @return [Array<Symbol>] filtered names
       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]
 
+      # Removes names that belong to any requested group.
+      # @param names [Array<Symbol>] names to filter
+      # @param groups [Array<Symbol>] group names
+      # @return [Array<Symbol>] filtered names
       def unpick(names, *groups) = names.reject { |name| groups.any? { is?(name, it) } }
 
+      # Removes ignored names from a list.
+      # @param names [Array<Symbol>, nil] names to filter
+      # @return [Array<Symbol>, nil] names that should be validated
       def concerns(names) = names ? names.reject { ignore?(it) } : names
 
+      # Installs low-level list helpers into data modules.
+      # @param base [Module] data module receiving helpers
+      # @return [void]
+      # @api private
       def self.extended(base) = base.extend(List)
     end
 
@@ -46,11 +72,21 @@ module Sevgi
 
       require_relative "data/specification"
 
+      # Returns expanded standard specification data for one element.
+      # @param name [Symbol] SVG element name
+      # @return [Hash, nil] expanded specification data
       def [](name) = expand(name)
 
+      # Reports whether a name is a data group name.
+      # @param name [Symbol] element or group name
+      # @return [Boolean]
       def group?(name) = /[[:upper:]]/.match?(name[0])
 
-      def model?(name, *models) = models.any? { (self[name] || {})[:model] == name }
+      # 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
+      # @return [Boolean]
+      def model?(name, *models) = models.any? { (self[name] || {})[:model] == it }
 
       private
 
@@ -58,7 +94,7 @@ module Sevgi
 
       def expand(name)
         @spec[name] ||= if data[name]
-          data[name].dup.tap do |spec|
+          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)
           end

data/lib/sevgi/standard/errors.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Sevgi
+  # Base class for SVG standard validation errors.
   class ValidationError < Error
+    # Builds a validation error with a context label and offending values.
+    # @param context [Object] validation context included in the error message
+    # @param args [Array<Object>, Object] invalid values included in the error message
+    # @return [void]
     def initialize(context, args = [])
       @context = context
       @args = Array(args)
@@ -9,8 +14,18 @@ module Sevgi
       super()
     end
 
-    def self.call(context, args = []) = raise new(context, args)
+    # Raises this validation error class.
+    # @param context [Object] validation context included in the error message
+    # @param args [Array<Object>, Object] invalid values included in the error message
+    # @return [void]
+    # @raise [Sevgi::ValidationError] always raises an instance of this class
+    def self.call(context, args = [])
+      raise new(context, args)
+    end
 
+    # Builds a validation error subclass with a fixed message fragment.
+    # @param message [String] message fragment placed after the validation context
+    # @return [Class<Sevgi::ValidationError>] validation error subclass
     def self.variant(message)
       Class.new(self) do
         define_method(:message) do
@@ -24,9 +39,14 @@ module Sevgi
     end
   end
 
+  # Raised when an element contains invalid attributes.
   InvalidAttributesError = ValidationError.variant("Invalid attribute(s)")
+  # Raised when an element contains invalid child elements.
   InvalidElementsError = ValidationError.variant("Invalid element(s)")
+  # Raised when character data appears where the SVG model forbids it.
   UnallowedCDataError = ValidationError.variant("Character data not allowed")
+  # Raised when an element contains disallowed child elements.
   UnallowedElementsError = ValidationError.variant("Element(s) not allowed")
+  # Raised when a conditional SVG content model requirement is not met.
   UnmetConditionError = ValidationError.variant("Condition unmet for the element")
 end

data/lib/sevgi/standard/internal.rb

@@ -2,13 +2,28 @@
 
 module Sevgi
   module Standard
+    # Low-level import and lookup helper for static SVG standard data.
+    # @api private
     module List
+      # Looks up a data entry.
+      # @param name [Symbol] data key
+      # @return [Object, nil] stored data value
       def [](name) = data[name]
 
+      # Imports new data entries without overwriting existing keys.
+      # @param kwargs [Hash] entries to import
+      # @return [Hash] backing data hash
       def import(**kwargs) = data.merge!(kwargs.reject { |key, _| data.key?(key) })
 
+      # Reports whether a data entry exists.
+      # @param name [Symbol] data key
+      # @return [Boolean]
       def valid?(name) = data.key?(name)
 
+      # Initializes the backing data hash on extended modules.
+      # @param base [Module] module receiving list behavior
+      # @return [void]
+      # @api private
       def self.extended(base)
         super
 

data/lib/sevgi/standard/model.rb

@@ -2,8 +2,16 @@
 
 module Sevgi
   module Standard
+    # SVG content model validators used by {Conform}.
+    # @api private
     module Model
+      # Validates elements that allow only character data.
       module CDataOnly
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedElementsError] when child elements are present
         def apply(cdata:, elements:)
           _cdata = cdata
 
@@ -11,7 +19,13 @@ module Sevgi
         end
       end
 
+      # Validates elements that allow character data or selected child elements.
       module CDataOrSomeElements
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
         def apply(cdata:, elements:)
           _cdata = cdata
 
@@ -20,7 +34,14 @@ module Sevgi
         end
       end
 
+      # Validates empty elements.
       module NoneElements
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when child elements are present
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -28,7 +49,14 @@ module Sevgi
         end
       end
 
+      # Validates elements that allow selected child elements but no character data.
       module SomeElements
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -37,8 +65,15 @@ module Sevgi
         end
       end
 
+      # Validates the special `feDiffuseLighting` content model.
       module SpecialFeDiffuseLighting
-        # Any number of Descriptive elements and exactly one FilterLightSource element, in any order.
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
+        # @raise [Sevgi::UnmetConditionError] when required light source elements are absent
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -52,8 +87,15 @@ module Sevgi
         end
       end
 
+      # Validates the special `feSpecularLighting` content model.
       module SpecialFeSpecularLighting
-        # Exactly one FilterLightSource element first and any number of Descriptive elements in any order.
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
+        # @raise [Sevgi::UnmetConditionError] when the first child is not a light source
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -67,8 +109,15 @@ module Sevgi
         end
       end
 
+      # Validates the special `font-face` content model.
       module SpecialFontFace
-        # Any number of Descriptive elements and at most one font-face element in any order.
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
+        # @raise [Sevgi::UnmetConditionError] when more than one `font-face` child is present
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 

data/lib/sevgi/standard/version.rb

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

data/lib/sevgi/standard.rb

@@ -11,21 +11,55 @@ require_relative "standard/conform"
 require_relative "standard/version"
 
 module Sevgi
+  # SVG standard data and validation helpers.
   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
     def attributes(...) = Attribute.set(...)
 
-    def attribute?(name) = Attribute.all.include?(name.to_sym)
+    # Reports whether an attribute name is recognized by the SVG standard data.
+    # @param name [Object] attribute name
+    # @return [Boolean]
+    def attribute?(name) = name.respond_to?(:to_sym) && Attribute.all.include?(name.to_sym)
 
+    # @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 cdata [String, nil] character data content
+    #   @param elements [Array<Symbol>, nil] child element names
+    #   @return [Boolean] true when the usage conforms
+    #   @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
     def elements(...) = Element.set(...)
 
-    def element?(name) = Element.all.include?(name.to_sym)
+    # Reports whether an element name is recognized by the SVG standard data.
+    # @param name [Object] element name
+    # @return [Boolean]
+    def element?(name) = name.respond_to?(:to_sym) && Element.all.include?(name.to_sym)
 
+    # @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
+    #   @return [Boolean]
     def model?(...) = Specification.model?(...)
 
-    def [](name) = Specification[name.to_sym]
+    # 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
+
+    alias [] specification
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-standard
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  version: 0.93.1
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,14 +15,14 @@ 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: Validates elements and attributes according to the SVG specification.
 email: roktas@gmail.com
 executables: []