Module: SvgConform::Interfaces::RequirementInterface

Included in:
Requirements::BaseRequirement
Defined in:
lib/svg_conform/interfaces/requirement_interface.rb

Overview

Defines the contract for validation requirements

All requirements must implement the methods defined in this interface. This ensures consistent behavior between DOM and SAX validation modes.

Examples:

Implementing a requirement

class MyRequirement < BaseRequirement
  include RequirementInterface

  def check(node, context)
    # DOM validation logic here
  end

  def validate_sax_element(element, context)
    # SAX validation logic here
  end
end

Instance Method Summary collapse

Instance Method Details

#check(node, context) ⇒ void

This method returns an undefined value.

Validates a single node during DOM traversal

This is the main validation method called for each node that passes the should_check_node? filter during DOM-based validation.

Examples:

Basic implementation

def check(node, context)
  if invalid_condition?(node)
    context.add_error(
      requirement_id: id,
      message: "Node violates requirement",
      node: node,
      severity: :error,
    )
  end
end

Parameters:

  • node (Moxml::Node, Nokogiri::XML::Node) —

    The node to validate

  • context (ValidationContext) —

    The validation context for reporting errors

Raises:

  • (NotImplementedError) —

    If not implemented by subclass



47
48
49
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 47

def check(node, context)
  raise NotImplementedError, "#{self.class} must implement #check"
end

#collect_sax_data(element, context) ⇒ void

This method returns an undefined value.

Collects data during SAX parsing for deferred validation

Called for each element during SAX parsing to collect data that will be used later in validate_sax_complete.

Use this for requirements that need to collect references, IDs, or other data before validating (e.g., ID/reference validation).

Parameters:



106
107
108
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 106

def collect_sax_data(element, context)
  # Default: no data collection
end

#needs_deferred_validation? ⇒ Boolean

Indicates if this requirement needs deferred validation

Return true if this requirement needs to validate after the full document is parsed (e.g., for ID/reference validation).

When returning true, also implement validate_sax_complete.

Returns:

  • (Boolean) —

    true if deferred validation is needed



134
135
136
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 134

def needs_deferred_validation?
  false
end

#reset_state ⇒ void

This method returns an undefined value.

Resets any state between validations (for batch mode)

Called between validations when validating multiple files. Override this method if your requirement maintains state that needs to be reset.



165
166
167
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 165

def reset_state
  # Default: no state to reset
end

#should_check_node?(node, context = nil) ⇒ Boolean

Determines if this requirement should check a specific node

Return false to skip validation for a node. The default implementation skips nodes that are not elements (text nodes, comments, etc.) and structurally invalid nodes.

Override this to add additional filtering logic.

Parameters:

  • node (Moxml::Node, Nokogiri::XML::Node, ElementProxy) —

    The node to check

  • context (ValidationContext, nil) (defaults to: nil) —

    The validation context (may be nil in some cases)

Returns:

  • (Boolean) —

    true if the node should be validated



149
150
151
152
153
154
155
156
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 149

def should_check_node?(node, context = nil)
  return false unless node.respond_to?(:name) && node.respond_to?(:attributes)

  # Skip structurally invalid nodes
  return false if context&.node_structurally_invalid?(node)

  true
end

#to_s ⇒ String

Returns a string representation of the requirement

Returns:

  • (String) —

    The requirement ID and description



172
173
174
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 172

def to_s
  "#{@id}: #{@description}"
end

#validate_document(document, context) ⇒ void

This method returns an undefined value.

Validates the entire document (called once per requirement)

Default implementation traverses the document and calls #check on each node that passes should_check_node?. Override for custom document-level validation logic.

Parameters:

  • document (Document) —

    The document to validate

  • context (ValidationContext) —

    The validation context for reporting errors



63
64
65
66
67
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 63

def validate_document(document, context)
  document.traverse do |node|
    check(node, context) if should_check_node?(node, context)
  end
end

#validate_sax_complete(context) ⇒ void

This method returns an undefined value.

Performs deferred validation after document is fully parsed

Called once after SAX parsing completes. Use this to validate relationships that require forward references (e.g., ID references, cross-element constraints).

Override this method and return true from needs_deferred_validation? to enable deferred validation for this requirement.

Parameters:

  • context (ValidationContext) —

    The validation context containing collected data and for reporting errors



122
123
124
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 122

def validate_sax_complete(context)
  # Default: no deferred validation
end

#validate_sax_element(element, context) ⇒ void

This method returns an undefined value.

Validates an element during SAX parsing

Called for each element during streaming SAX validation. Override this method to implement SAX-compatible validation logic.

IMPORTANT: In SAX mode, the element is an ElementProxy (not a full DOM node). It provides: name, attributes, parent, path, position but NOT:

  • children (not yet parsed)
  • tree traversal (impossible during streaming)
  • XPath queries (not available)

Use ElementProxy methods:

  • element.name - element tag name
  • element.attributes - hash of attributes
  • element.parent - parent ElementProxy
  • element.path - array of element names representing path
  • element.position - 1-based position in document
  • element.path_id - unique node ID for tracking

Parameters:



91
92
93
 
# File 'lib/svg_conform/interfaces/requirement_interface.rb', line 91

def validate_sax_element(element, context)
  # Default: Empty - subclasses must override for SAX support
end