Configure and customize Canon’s behavior for your specific needs.

1. Overview

Canon provides extensive configuration options to control how documents are processed, compared, and displayed. This section covers all configurable features organized by the 4-layer architecture.

2. Configuration Layers

Canon’s comparison system has 4 distinct configuration layers:

Layer 1: Preprocessing

Transform documents before comparison to normalize formatting.

Options: none, c14n, normalize, format

Layer 2: Algorithm Selection (see Algorithms)

Choose the comparison strategy.

Options: dom (stable), semantic (experimental)

Layer 3: Match Options

Configure what to compare and how strictly.

  • Match dimensions (granular control)

  • Match profiles (preset combinations)

Layer 4: Diff Formatting

Control how differences are displayed.

  • Diff modes (by_line, by_object)

  • Colors and symbols

  • Context and grouping

  • Character visualization

3. Feature Categories

3.1. Canonicalization

Canonicalization

Format-specific rules for converting documents to canonical form.

3.2. Match Configuration

Match Options

Fine-grained control over comparison behavior.

3.3. Processing

Preprocessing

Transform documents before comparison.

3.4. Output Customization

Diff Formatting

Customize how differences are displayed.

3.5. Configuration Profiles

Configuration Profiles

Bundle all settings into named presets defined in YAML.

  • Built-in profiles (metanorma, metanorma_debug)

  • Custom profiles from local YAML files

  • Profile inheritance

3.6. System Configuration

Environment Configuration

System-level settings and limits.

Input Validation

Error handling and validation.

  • Syntax validation

  • Format detection

  • Error messages

3.7. Performance

Performance

Performance benchmarking and optimization.

  • SAX-based XML parser

  • Benchmark categories

  • CI integration

  • Regression detection

4. Quick Configuration Examples

4.1. Test-Friendly Comparison

Ignore formatting differences for testing:

Canon::Comparison.equivalent?(expected, actual,
  match_profile: :spec_friendly
)

4.2. Canonical Comparison

Compare after canonicalization:

Canon::Comparison.equivalent?(doc1, doc2,
  preprocessing: :c14n,
  match_profile: :strict
)

4.3. Custom Match Dimensions

Fine-grained control:

Canon::Comparison.equivalent?(doc1, doc2,
  match: {
    text_content: :normalize,
    structural_whitespace: :ignore,
    attribute_order: :ignore
  }
)

4.4. Verbose Diff with Color

Detailed output:

result = Canon::Comparison.compare(doc1, doc2,
  verbose: true,
  use_color: true,
  context_lines: 5
)
puts result.diff

5. Common Use Cases

Testing generated output

Use match_profile: :spec_friendly to ignore formatting differences.

Validating canonicalization

Use preprocessing: :c14n with match_profile: :strict for exact comparison.

Debugging whitespace issues

Enable character visualization to see invisible characters.

Comparing large files

Configure size limits to prevent hangs.

6. Next Steps

7. See Also

Table of contents