Learn how to use Canon through different interfaces.

1. Overview

Canon provides three main interfaces for different use cases:

Ruby API

Integrate Canon into Ruby applications for programmatic formatting and comparison.

Command-Line Interface

Use Canon from the terminal for one-off tasks and shell scripting.

RSpec Matchers

Test XML, JSON, and YAML generation with semantic matchers.

2. Choosing an Interface

Use Ruby API when

  • Integrating into a Ruby application

  • Need programmatic control

  • Building custom tooling

  • Processing multiple files

Use CLI when

  • Running one-off comparisons

  • Shell scripting

  • CI/CD pipelines

  • Quick formatting tasks

Use RSpec when

  • Writing tests

  • Validating generated output

  • TDD/BDD workflows

  • Continuous integration

3. Common Patterns Across Interfaces

All interfaces share the same core concepts:

  • Formats: XML, HTML, JSON, YAML

  • Operations: Format (canonicalize/pretty-print) and Compare

  • Options: Match dimensions, profiles, preprocessing

  • Output: Color-coded diffs, character visualization

The interface you choose determines how you invoke these features, but the underlying behavior is consistent.

4. Quick Examples

4.1. Format a File

Ruby:

Canon.format(xml_string, :xml, mode: :pretty)

CLI:

canon format file.xml --mode pretty

4.2. Compare Files

Ruby:

Canon::Comparison.equivalent?(doc1, doc2)

CLI:

canon diff file1.xml file2.xml

RSpec:

expect(actual_xml).to be_xml_equivalent_to(expected_xml)

5. Next Steps

  • Choose your primary interface and dive into its documentation

  • Review Match Options to understand configuration

  • Check Guides for task-oriented tutorials

6. See Also

Table of contents