canon 0.1.3 → 0.1.5

data/docs/MATCH_OPTIONS.adoc

@@ -0,0 +1,719 @@
+---
+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)
+====
+
+== 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
+}
+----
+
+.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
+}
+----
+
+.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
+}
+----
+
+.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
+}
+----
+
+.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`
+|`:strict`
+|`:ignore`
+|—
+|—
+
+|`attribute_values`
+|`:strict`
+|`:strict`
+|—
+|—
+
+|`key_order`
+|—
+|—
+|`:strict`
+|`:strict`
+
+|`comments`
+|`:strict`
+|`:ignore`
+|—
+|`: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
+  }
+)
+----
+
+=== 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
+----
+
+=== 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
+  )
+----
+
+== 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]