canon 0.1.8 → 0.1.10

data/old-docs/MATCH_OPTIONS.adoc

@@ -1,912 +0,0 @@
----
-layout: default
-title: Match Options
-nav_order: 30
-parent: Customizing Behavior
----
-= Match options
-:toc:
-:toclevels: 3
-
-== Scope
-
-This document provides a complete reference for Canon's match options,
-including match dimensions, behaviors, and predefined profiles.
-
-Match options control Phase 2 (semantic matching) of Canon's comparison
-architecture. See link:MATCH_ARCHITECTURE[Match architecture] for the
-complete flow.
-
-== General
-
-Match options control which aspects of documents are compared and how
-strictly they are compared. Canon provides:
-
-* **Match dimensions**: Independent aspects of documents (text, whitespace,
-attributes, etc.)
-* **Dimension behaviors**: How each dimension is compared (`:strict`,
-`:normalize`, `:ignore`)
-* **Match profiles**: Predefined combinations for common scenarios
-
-== Match dimensions
-
-Match dimensions are orthogonal aspects that can be configured independently.
-
-=== text_content
-
-**Applies to**: All formats
-
-**Purpose**: Controls how text content within elements/values is compared.
-
-**Behaviors**:
-
-`:strict`:: Text must match exactly, character-for-character including all
-whitespace
-
-`:normalize`:: Whitespace is normalized (collapsed/trimmed) before comparison
-
-`:ignore`:: Text content is completely ignored in comparison
-
-.text_content examples
-[example]
-====
-**Input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<message>Hello   World</message>
-
-<!-- File 2 -->
-<message>Hello World</message>
-----
-
-**Results**:
-
-* `:strict` → Different (whitespace differs: 3 spaces vs 1 space)
-* `:normalize` → Equivalent (both normalize to "Hello World")
-* `:ignore` → Equivalent (text content ignored, structure matches)
-====
-
-=== structural_whitespace
-
-**Applies to**: All formats
-
-**Purpose**: Controls how whitespace between elements (indentation, newlines)
-is handled.
-
-**Behaviors**:
-
-`:strict`:: All structural whitespace must match exactly
-
-`:normalize`:: Structural whitespace is normalized
-
-`:ignore`:: Structural whitespace is completely ignored
-
-.structural_whitespace examples
-[example]
-====
-**Input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<root>
-  <item>A</item>
-  <item>B</item>
-</root>
-
-<!-- File 2 -->
-<root><item>A</item><item>B</item></root>
-----
-
-**Results**:
-
-* `:strict` → Different (indentation and newlines differ)
-* `:normalize` → Equivalent (whitespace between elements normalized)
-* `:ignore` → Equivalent (only element structure compared)
-====
-
-=== attribute_whitespace
-
-**Applies to**: XML, HTML only
-
-**Purpose**: Controls how whitespace in attribute values is handled.
-
-**Behaviors**:
-
-`:strict`:: Attribute value whitespace must match exactly
-
-`:normalize`:: Whitespace in attribute values is normalized
-
-`:ignore`:: Whitespace in attribute values is ignored
-
-.attribute_whitespace examples
-[example]
-====
-**Input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<div class="item  active">Content</div>
-
-<!-- File 2 -->
-<div class="item active">Content</div>
-----
-
-**Results**:
-
-* `:strict` → Different (2 spaces vs 1 space)
-* `:normalize` → Equivalent ("item  active" normalizes to "item active")
-* `:ignore` → Equivalent (only attribute presence compared)
-
-**HTML `class` attribute special handling**:
-
-HTML's `class` attribute is space-separated, so normalization is particularly
-useful:
-
-[source,html]
-----
-<!-- These are equivalent with :normalize -->
-<div class="btn  primary   active">Click</div>
-<div class="btn primary active">Click</div>
-----
-====
-
-=== attribute_order
-
-**Applies to**: XML, HTML only
-
-**Purpose**: Controls whether attribute order matters.
-
-**Behaviors**:
-
-`:strict`:: Attributes must appear in the same order
-
-`:ignore`:: Attribute order doesn't matter (set-based comparison)
-
-.attribute_order examples
-[example]
-====
-**Input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<element id="123" class="active" data-value="test"/>
-
-<!-- File 2 -->
-<element class="active" data-value="test" id="123"/>
-----
-
-**Results**:
-
-* `:strict` → Different (attribute order differs)
-* `:ignore` → Equivalent (same attributes present, unordered comparison)
-
-**HTML default**:
-
-HTML attributes are inherently unordered per the HTML specification, so the
-default for HTML is `:ignore`:
-
-[source,html]
-----
-<!-- These are always equivalent for HTML -->
-<input type="text" id="name" class="form-control">
-<input class="form-control" id="name" type="text">
-----
-====
-
-=== attribute_values
-
-**Applies to**: XML, HTML only
-
-**Purpose**: Controls how attribute values are compared.
-
-**Behaviors**:
-
-`:strict`:: Attribute values must match exactly
-
-`:normalize`:: Whitespace in values is normalized
-
-`:ignore`:: Only attribute presence is checked, values ignored
-
-.attribute_values examples
-[example]
-====
-**Input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<element id="123" class="normative"/>
-
-<!-- File 2 -->
-<element id="456" class="informative"/>
-----
-
-**Results**:
-
-* `:strict` → Different (attribute values differ)
-* `:normalize` → Different (values still differ after normalization)
-* `:ignore` → Equivalent (both have `id` and `class` attributes, values
-ignored)
-
-**Use case**: Useful when you want to verify that certain attributes exist
-but don't care about their specific values (e.g., testing that generated IDs
-are present).
-====
-
-=== key_order
-
-**Applies to**: JSON, YAML only
-
-**Purpose**: Controls whether object key order matters.
-
-**Behaviors**:
-
-`:strict`:: Keys must appear in the same order
-
-`:ignore`:: Key order doesn't matter (unordered comparison)
-
-.key_order examples
-[example]
-====
-**JSON input**:
-
-[source,json]
-----
-// File 1
-{
-  "name": "John",
-  "age": 30,
-  "city": "NYC"
-}
-
-// File 2
-{
-  "city": "NYC",
-  "name": "John",
-  "age": 30
-}
-----
-
-**Results**:
-
-* `:strict` → Different (key order differs)
-* `:ignore` → Equivalent (same keys and values, unordered)
-
-**YAML input**:
-
-[source,yaml]
-----
-# File 1
-name: John
-age: 30
-city: NYC
-
-# File 2
-city: NYC
-name: John
-age: 30
-----
-
-**Results**:
-
-* `:strict` → Different (key order differs)
-* `:ignore` → Equivalent (same structure and values)
-====
-
-=== comments
-
-**Applies to**: XML, HTML, YAML (JSON doesn't support comments in standard
-spec)
-
-**Purpose**: Controls how comments are compared.
-
-**Behaviors**:
-
-`:strict`:: Comments must match exactly (including whitespace)
-
-`:normalize`:: Whitespace in comments is normalized
-
-`:ignore`:: Comments are completely ignored
-
-.comments examples
-[example]
-====
-**XML input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<root>
-  <!-- This is a comment -->
-  <element>Value</element>
-</root>
-
-<!-- File 2 -->
-<root>
-  <element>Value</element>
-</root>
-----
-
-**Results**:
-
-* `:strict` → Different (File 1 has a comment, File 2 doesn't)
-* `:normalize` → Different (still different, comment present vs absent)
-* `:ignore` → Equivalent (comments ignored, structure matches)
-
-**YAML input**:
-
-[source,yaml]
-----
-# File 1
-# Configuration file
-name: test
-# Database settings
-database: prod
-
-# File 2
-name: test
-database: prod
-----
-
-**Results**:
-
-* `:strict` → Different (comments differ)
-* `:normalize` → Different (comments still differ)
-* `:ignore` → Equivalent (comments ignored)
-====
-
-=== element_structure
-
-**Applies to**: All formats (primarily used with semantic diff algorithm)
-
-**Purpose**: Controls how element/node type changes are handled during
-semantic tree comparison.
-
-**Behaviors**:
-
-`:strict`:: Element type changes are treated as differences
-
-`:ignore`:: Element type changes are ignored if content is similar
-
-**Note**: This dimension is primarily used by the semantic diff algorithm to
-detect structural changes like element upgrades/downgrades (e.g., `<p>` to
-`<div>`).
-
-.element_structure examples
-[example]
-====
-**XML input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<document>
-  <paragraph>Text content</paragraph>
-</document>
-
-<!-- File 2 -->
-<document>
-  <section>Text content</section>
-</document>
-----
-
-**Results with semantic algorithm**:
-
-* `:strict` → Different (element types differ: paragraph vs section)
-* `:ignore` → Potentially equivalent (if content matches, type change ignored)
-
-**Use case**: Useful when refactoring markup where element names change but
-semantic content remains the same.
-====
-
-=== element_position
-
-**Applies to**: All formats (primarily used with semantic diff algorithm)
-
-**Purpose**: Controls how element position/order changes are detected and
-reported.
-
-**Behaviors**:
-
-`:strict`:: Element positions must match exactly
-
-`:ignore`:: Element reordering is allowed if content matches
-
-**Note**: This dimension enables the semantic diff algorithm to detect move
-operations when elements are reordered.
-
-.element_position examples
-[example]
-====
-**XML input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<list>
-  <item id="a">First</item>
-  <item id="b">Second</item>
-  <item id="c">Third</item>
-</list>
-
-<!-- File 2 -->
-<list>
-  <item id="b">Second</item>
-  <item id="a">First</item>
-  <item id="c">Third</item>
-</list>
-----
-
-**Results with semantic algorithm**:
-
-* `:strict` → Different (items a and b are in different positions)
-* `:ignore` → Equivalent (same items present, order doesn't matter)
-
-**Use case**: Useful when testing JSON arrays or XML lists where order may
-vary but content is equivalent.
-====
-
-=== element_hierarchy
-
-**Applies to**: All formats (primarily used with semantic diff algorithm)
-
-**Purpose**: Controls how hierarchical structure changes are detected, such
-as elements being moved to different parent nodes.
-
-**Behaviors**:
-
-`:strict`:: Elements must maintain exact parent-child relationships
-
-`:ignore`:: Elements can move between parents if content matches
-
-**Note**: This dimension enables the semantic diff algorithm to detect when
-elements are reorganized into different hierarchical structures.
-
-.element_hierarchy examples
-[example]
-====
-**XML input**:
-
-[source,xml]
-----
-<!-- File 1 -->
-<document>
-  <section>
-    <note>Important information</note>
-  </section>
-</document>
-
-<!-- File 2 -->
-<document>
-  <note>Important information</note>
-  <section>
-  </section>
-</document>
-----
-
-**Results with semantic algorithm**:
-
-* `:strict` → Different (note moved from section child to document child)
-* `:ignore` → Potentially equivalent (note content preserved, hierarchy
-change ignored)
-
-**Use case**: Useful when restructuring documents where content blocks move
-between sections but the content itself remains unchanged.
-====
-
-== Match profiles
-
-Profiles are predefined combinations of dimension settings for common
-scenarios.
-
-=== strict
-
-**Purpose**: Exact matching - all dimensions use `:strict` behavior.
-
-**When to use**:
-
-* Character-perfect matching required
-* Testing exact serializer output
-* Verifying formatting compliance
-* Maximum strictness needed
-
-**Settings**:
-
-[source,ruby]
-----
-{
-  preprocessing: :none,
-  text_content: :strict,
-  structural_whitespace: :strict,
-  attribute_whitespace: :strict,
-  attribute_order: :strict,
-  attribute_values: :strict,
-  key_order: :strict,
-  comments: :strict,
-  element_structure: :strict,
-  element_position: :strict,
-  element_hierarchy: :strict
-}
-----
-
-.strict profile usage
-[example]
-====
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2,
-  match_profile: :strict
-)
-----
-
-Every aspect must match exactly.
-====
-
-=== rendered
-
-**Purpose**: Mimics how browsers/CSS engines render content.
-
-**When to use**:
-
-* Comparing HTML rendered output
-* Formatting doesn't affect display
-* Testing web page generation
-* Browser-equivalent comparison
-
-**Settings**:
-
-[source,ruby]
-----
-{
-  preprocessing: :none,
-  text_content: :normalize,
-  structural_whitespace: :normalize,
-  attribute_whitespace: :normalize,
-  attribute_order: :ignore,
-  attribute_values: :strict,
-  key_order: :ignore,
-  comments: :ignore,
-  element_structure: :strict,
-  element_position: :strict,
-  element_hierarchy: :strict
-}
-----
-
-.rendered profile usage
-[example]
-====
-[source,ruby]
-----
-Canon::Comparison.equivalent?(html1, html2,
-  match_profile: :rendered
-)
-----
-
-Focuses on how content would appear in a browser.
-====
-
-=== spec_friendly
-
-**Purpose**: Test-friendly comparison that ignores most formatting
-differences.
-
-**When to use**:
-
-* Writing RSpec tests
-* Testing semantic correctness
-* Ignoring pretty-printing differences
-* Most common test scenario
-
-**Settings**:
-
-[source,ruby]
-----
-{
-  preprocessing: :normalize,
-  text_content: :normalize,
-  structural_whitespace: :ignore,
-  attribute_whitespace: :normalize,
-  attribute_order: :ignore,
-  attribute_values: :strict,
-  key_order: :ignore,
-  comments: :ignore,
-  element_structure: :strict,
-  element_position: :ignore,
-  element_hierarchy: :strict
-}
-----
-
-.spec_friendly profile usage
-[example]
-====
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2,
-  match_profile: :spec_friendly
-)
-----
-
-Focuses on content, not formatting.
-====
-
-=== content_only
-
-**Purpose**: Only semantic content matters - maximum tolerance for formatting.
-
-**When to use**:
-
-* Only care about data, not presentation
-* Maximum flexibility needed
-* Comparing across different formats
-* Structural equivalence only
-
-**Settings**:
-
-[source,ruby]
-----
-{
-  preprocessing: :normalize,
-  text_content: :normalize,
-  structural_whitespace: :ignore,
-  attribute_whitespace: :ignore,
-  attribute_order: :ignore,
-  attribute_values: :ignore,
-  key_order: :ignore,
-  comments: :ignore,
-  element_structure: :ignore,
-  element_position: :ignore,
-  element_hierarchy: :ignore
-}
-----
-
-.content_only profile usage
-[example]
-====
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2,
-  match_profile: :content_only
-)
-----
-
-Maximum tolerance, content focus only.
-====
-
-== Format defaults
-
-Each format has sensible defaults based on typical usage:
-
-[cols="1,1,1,1,1"]
-|===
-|Dimension |XML |HTML |JSON |YAML
-
-|`text_content`
-|`:strict`
-|`:normalize`
-|`:strict`
-|`:strict`
-
-|`structural_whitespace`
-|`:strict`
-|`:normalize`
-|`:strict`
-|`:strict`
-
-|`attribute_whitespace`
-|`:strict`
-|`:normalize`
-|—
-|—
-
-|`attribute_order`
-|`:ignore`
-|`:ignore`
-|—
-|—
-
-|`attribute_values`
-|`:strict`
-|`:strict`
-|—
-|—
-
-|`key_order`
-|—
-|—
-|`:strict`
-|`:strict`
-
-|`comments`
-|`:strict`
-|`:ignore`
-|—
-|`:strict`
-
-|`element_structure`
-|`:strict`
-|`:strict`
-|`:strict`
-|`:strict`
-
-|`element_position`
-|`:strict`
-|`:strict`
-|`:strict`
-|`:strict`
-
-|`element_hierarchy`
-|`:strict`
-|`:strict`
-|`:strict`
-|`:strict`
-|===
-
-== Configuration precedence
-
-When options are specified in multiple places, Canon resolves them using this
-hierarchy (highest to lowest priority):
-
-[source]
-----
-1. Per-comparison explicit options (highest)
-   ↓
-2. Per-comparison profile
-   ↓
-3. Global configuration explicit options
-   ↓
-4. Global configuration profile
-   ↓
-5. Format defaults (lowest)
-----
-
-.Precedence example
-[example]
-====
-**Global configuration**:
-
-[source,ruby]
-----
-Canon::RSpecMatchers.configure do |config|
-  config.xml.match.profile = :spec_friendly
-  config.xml.match.options = { comments: :strict }
-end
-----
-
-The `:spec_friendly` profile sets:
-
-* `text_content: :normalize`
-* `structural_whitespace: :ignore`
-* `comments: :ignore`
-
-But the explicit `comments: :strict` overrides the profile setting.
-
-**Per-test usage**:
-
-[source,ruby]
-----
-expect(actual).to be_xml_equivalent_to(expected)
-  .with_profile(:rendered)
-  .with_options(structural_whitespace: :ignore)
-----
-
-**Final resolved options**:
-
-* `text_content: :normalize` (from `:rendered` per-test profile)
-* `structural_whitespace: :ignore` (from per-test explicit option)
-* `comments: :strict` (from global explicit option)
-* Other dimensions use `:rendered` profile or format defaults
-====
-
-== Usage
-
-=== Ruby API
-
-[source,ruby]
-----
-# Use specific dimensions
-Canon::Comparison.equivalent?(doc1, doc2,
-  match: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    comments: :ignore
-  }
-)
-
-# Use a profile
-Canon::Comparison.equivalent?(doc1, doc2,
-  match_profile: :spec_friendly
-)
-
-# Profile with dimension overrides
-Canon::Comparison.equivalent?(doc1, doc2,
-  match_profile: :spec_friendly,
-  match: {
-    comments: :strict  # Override profile
-  }
-)
-
-# Use semantic dimensions
-Canon::Comparison.equivalent?(doc1, doc2,
-  diff_algorithm: :semantic,
-  match: {
-    element_position: :ignore,
-    element_hierarchy: :ignore
-  }
-)
-----
-
-=== CLI
-
-[source,bash]
-----
-# Use profile
-$ canon diff file1.xml file2.xml \
-  --match-profile spec_friendly \
-  --verbose
-
-# Override specific dimensions
-$ canon diff file1.xml file2.xml \
-  --text-content normalize \
-  --structural-whitespace ignore \
-  --verbose
-
-# Combine profile with overrides
-$ canon diff file1.xml file2.xml \
-  --match-profile spec_friendly \
-  --comments strict \
-  --verbose
-
-# Use semantic algorithm with flexible positioning
-$ canon diff file1.xml file2.xml \
-  --diff-algorithm semantic \
-  --element-position ignore \
-  --verbose
-----
-
-=== RSpec
-
-[source,ruby]
-----
-# Global configuration
-Canon::RSpecMatchers.configure do |config|
-  config.xml.match.profile = :spec_friendly
-  config.xml.match.options = {
-    text_content: :normalize,
-    comments: :ignore
-  }
-end
-
-# Per-test override
-expect(actual).to be_xml_equivalent_to(expected)
-  .with_profile(:strict)
-
-# Per-test dimension override
-expect(actual).to be_xml_equivalent_to(expected)
-  .with_options(
-    structural_whitespace: :strict,
-    text_content: :strict
-  )
-
-# Semantic algorithm with flexible hierarchy
-expect(actual).to be_xml_equivalent_to(expected,
-  diff_algorithm: :semantic
-)
-  .with_options(
-    element_position: :ignore,
-    element_hierarchy: :ignore
-  )
-----
-
-== See also
-
-* link:MATCH_ARCHITECTURE[Match architecture]
-* link:PREPROCESSING[Preprocessing options]
-* link:FORMATS[Format support]
-* link:RUBY_API[Ruby API documentation]
-* link:CLI[Command-line interface]
-* link:RSPEC[RSpec matchers]