canon 0.1.5 → 0.1.7

data/docs/features/match-options/index.adoc

@@ -0,0 +1,621 @@
+---
+title: Match Options
+parent: Features
+nav_order: 3
+has_children: true
+---
+= Match options
+:toc:
+:toclevels: 3
+
+== Purpose
+
+This section provides a complete reference for Canon's match options, including match dimensions, behaviors, and predefined profiles.
+
+Match options control **Layer 3 (Match Options)** of Canon's 4-layer comparison architecture. See link:../../understanding/comparison-pipeline.adoc[Comparison Pipeline] for the complete flow.
+
+== Overview
+
+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
+
+**Important**: Match options behave differently with each algorithm. See link:algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] for details.
+
+== Child Pages
+
+* link:dimensions.adoc[Match Dimensions] - Detailed reference for all dimensions
+* link:profiles.adoc[Match Profiles] - Predefined configurations
+* link:algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How DOM and Semantic algorithms interpret options differently
+* link:html-policies.adoc[HTML-Specific Policies] - HTML format-specific comparison policies
+
+== Match dimensions overview
+
+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
+
+=== 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
+
+=== 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_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_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
+
+=== 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)
+
+=== 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
+
+=== namespace_uri
+
+**Applies to**: XML only
+
+**Purpose**: Controls how XML element namespaces are compared. Elements are identified by the pair `{namespace_uri, local_name}` according to XML semantics.
+
+**Behaviors**:
+
+`:strict`:: Namespace URIs must match (default and only supported behavior)
+
+**Note**: This dimension is always `:strict` for XML. Namespace prefixes are not significant - only the namespace URI matters. Elements with different prefixes but the same namespace URI are considered equivalent.
+
+.Namespace URI comparison
+[example]
+====
+[source,ruby]
+----
+# These are equivalent (same namespace URI, different prefixes)
+xml1 = '<root xmlns:a="http://example.com"><a:item>value</a:item></root>'
+xml2 = '<root xmlns:b="http://example.com"><b:item>value</b:item></root>'
+
+# These are NOT equivalent (different namespace URIs)
+xml3 = '<root xmlns:a="http://example.com"><a:item>value</a:item></root>'
+xml4 = '<root xmlns:a="http://other.com"><a:item>value</a:item></root>'
+----
+====
+
+== Match profiles overview
+
+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
+
+=== 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
+
+=== 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
+
+=== 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
+
+== 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`
+
+|`namespace_uri`
+|`: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 examples
+
+=== 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
+  )
+====
+
+== Comments dimension
+
+The `comments` dimension controls how comment nodes are matched and how their differences are classified in diff output.
+
+=== Matching behaviors
+
+`strict`:: Comment content must match exactly. Differences are classified as **normative** (shown in red/green).
+`normalize`:: Comment text is normalized (whitespace collapsed) before matching. Differences are still classified as **normative**.
+`ignore`:: Comment content is compared but differences are classified as **informative** (shown in cyan/blue) rather than normative.
+
+IMPORTANT: With `comments: :ignore`, comment nodes still participate in comparison and create DiffNodes. The difference is that these DiffNodes are marked as **informative** rather than **normative**. Use the `show_diffs` option to control visibility of informative diffs in the output.
+
+=== Default values
+
+* **XML**: `comments: :strict` - Comment differences are normative
+* **HTML**: `comments: :ignore` - Comment differences are informative
+
+=== Example: Comments as informative differences
+
+.Match comments but classify differences as informative
+[source,ruby]
+----
+xml1 = '<root><!--comment 1--><child>text</child></root>'
+xml2 = '<root><!--comment 2--><child>text</child></root>'
+
+Canon.equivalent?(xml1, xml2,
+  format: :xml,
+  verbose: true,
+  match: { comments: :ignore },  # Comment diffs → informative
+  show_diffs: :all                # Show all diffs (cyan for comments)
+)
+----
+
+In this example, the comment difference is still detected and included in the diff output, but is shown in cyan color to indicate it's an informative difference.
+
+=== Example: Hide informative differences
+
+.Hide informative differences including comments
+[source,ruby]
+----
+Canon.equivalent?(xml1, xml2,
+  format: :xml,
+  verbose: true,
+  match: { comments: :ignore },   # Comment diffs → informative
+  show_diffs: :normative          # Hide informative diffs
+)
+# Returns empty string - no normative diffs to show
+----
+
+== Controlling diff visibility with show_diffs
+
+The `show_diffs` option controls which differences appear in verbose output. This provides fine-grained control over what is displayed without affecting the comparison algorithm.
+
+=== Values
+
+`:all` (default):: Show all differences (both normative and informative)
+`:normative`:: Show only normative differences (hide informative)
+`:informative`:: Show only informative differences (hide normative)
+
+=== Color scheme
+
+Normative differences:: Shown in red (removed) and green (added)
+Informative differences:: Shown in cyan/blue (both removed and added)
+
+=== Three-stage pipeline
+
+The comparison process follows a three-stage pipeline:
+
+[source]
+----
+┌─────────────────────────────────────────────────────────────┐
+│  STAGE 1: MATCHING - Compare all nodes                      │
+│  • Parse XML/HTML to DOM or TreeNode                         │
+│  • Compare ALL nodes (including comments)                    │
+│  • Create DiffNodes for ALL differences                      │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  STAGE 2: CLASSIFICATION - Mark normative vs informative    │
+│  • DiffClassifier uses match_options                         │
+│  • comments: :ignore → comment diffs = informative           │
+│  • comments: :strict → comment diffs = normative             │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  STAGE 3: RENDERING - Control visibility                    │
+│  • show_diffs: :all → show everything                        │
+│  • show_diffs: :normative → show only normative              │
+│  • show_diffs: :informative → show only informative          │
+└─────────────────────────────────────────────────────────────┘
+----
+
+=== Example: Show only normative differences
+
+.Show only normative differences (common use case)
+[source,ruby]
+----
+result = Canon.equivalent?(xml1, xml2,
+  format: :xml,
+  verbose: true,
+  show_diffs: :normative
+)
+----
+
+This is useful when you want to focus on actual semantic differences and hide cosmetic ones like comment changes or whitespace formatting.
+
+=== Example: Show only informative differences
+
+.Show only informative differences (debugging use case)
+[source,ruby]
+----
+result = Canon.equivalent?(xml1, xml2,
+  format: :xml,
+  verbose: true,
+  show_diffs: :informative
+)
+----
+
+This is useful for debugging or reviewing formatting/cosmetic changes separately from semantic ones.
+
+=== Combining comments and show_diffs
+
+The `comments` match option and `show_diffs` option work together:
+
+[cols="1,1,2"]
+|===
+| comments | show_diffs | Result
+
+| `:ignore`
+| `:normative`
+| Comment diffs hidden (informative)
+
+| `:ignore`
+| `:all`
+| Comment diffs shown in cyan (informative)
+
+| `:strict`
+| `:normative`
+| Comment diffs shown in red/green (normative)
+
+| `:strict`
+| `:informative`
+| Comment diffs hidden (normative)
+|===
+
+.Example: Mixed scenario
+// XML with both comment and text differences
+xml1 = '<root><!--old comment--><child>text1</child></root>'
+xml2 = '<root><!--new comment--><child>text2</child></root>'
+
+// Show only normative diffs (hide comment changes)
+result = Canon.equivalent?(xml1, xml2,
+  format: :xml,
+  verbose: true,
+  match: { comments: :ignore, text_content: :strict },
+  show_diffs: :normative
+)
+
+// Output shows text change but not comment change
+// - text1 (in red)
+// + text2 (in green)
+// Comment diff is hidden because it's informative
+----
+
+=== CLI usage
+
+[source,bash]
+----
+# Show only normative differences
+canon diff file1.xml file2.xml --show-diffs=normative
+
+# Show all differences (default)
+canon diff file1.xml file2.xml --show-diffs=all
+
+# Show only informative differences
+canon diff file1.xml file2.xml --show-diffs=informative
+----
+
+=== RSpec usage
+
+[source,ruby]
+----
+RSpec.describe 'XML comparison' do
+  it 'matches despite comment differences' do
+    expect(xml1).to be_xml_equivalent_to(xml2)
+      .with_match(comments: :ignore)
+      .show_diffs(:normative)
+  end
+end
+----
+
+=== Environment variable
+
+You can set a default value using the `CANON_SHOW_DIFFS` environment variable:
+
+[source,bash]
+----
+export CANON_SHOW_DIFFS=normative
+----
+
+Valid values: `all`, `normative`, `informative`

data/docs/getting-started/index.adoc

@@ -0,0 +1,83 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+has_children: true
+---
+= Getting Started
+
+Welcome to Canon! This section will help you get up and running quickly.
+
+== Overview
+
+Canon is a Ruby library for canonicalization, pretty-printing, and semantic comparison of structured documents in multiple formats (XML, HTML, JSON, YAML).
+
+Whether you're:
+
+* A developer integrating Canon into an application
+* A QA engineer writing tests for document generation
+* A DevOps engineer comparing configuration files
+* An architect evaluating Canon's design
+
+This section provides everything you need to start using Canon effectively.
+
+== What You'll Learn
+
+This section covers:
+
+link:installation[**Installation**]::
+How to install Canon in your Ruby environment, including gem installation and bundler setup.
+
+link:quick-start[**Quick Start**]::
+Your first Canon operations - formatting and comparing documents with minimal code.
+
+link:core-concepts[**Core Concepts**]::
+Essential concepts to understand how Canon works: canonicalization, semantic comparison, and diff modes.
+
+== Quick Example
+
+Here's a taste of what Canon can do:
+
+[source,ruby]
+----
+require 'canon'
+
+# Format XML in canonical form
+xml = '<root><b>2</b><a>1</a></root>'
+canonical = Canon.format(xml, :xml, mode: :c14n)
+# => "<root><a>1</a><b>2</b></root>"
+
+# Compare documents semantically
+doc1 = '<root><a>1</a><b>2</b></root>'
+doc2 = '<root>  <b>2</b>  <a>1</a>  </root>'
+Canon::Comparison.equivalent?(doc1, doc2)
+# => true (ignores whitespace and element order)
+----
+
+== Next Steps
+
+After completing this section:
+
+* Explore link:../interfaces/[Interfaces] to learn Ruby API, CLI, and RSpec usage
+* Read link:../understanding/[Understanding Canon] to learn how it works internally
+* Check link:../features/[Features] to customize Canon's behavior
+
+== Common Questions
+
+**Which Ruby versions are supported?**::
+Canon supports Ruby 2.7 and higher.
+
+**What formats does Canon support?**::
+XML, HTML, JSON, and YAML. See link:../understanding/formats/[Format Support] for details.
+
+**Can I use Canon without RSpec?**::
+Yes! Canon works as a standalone library. RSpec matchers are optional.
+
+**Is Canon suitable for production use?**::
+Yes. The core DOM diff algorithm is stable and well-tested. The semantic tree diff is experimental.
+
+== See Also
+
+* link:../interfaces/[Interfaces] - Choose your preferred way to use Canon
+* link:../understanding/formats/[Format Support] - Format-specific details
+* link:../features/match-options/[Match Options] - Customizing comparison behavior