Welcome to Canon! This section will help you get up and running quickly.

1. 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.

2. What You’ll Learn

This section covers:

Installation

How to install Canon in your Ruby environment, including gem installation and bundler setup.

Quick Start

Your first Canon operations - formatting and comparing documents with minimal code.

Core Concepts

Essential concepts to understand how Canon works: canonicalization, semantic comparison, and diff modes.

3. Quick Example

Here’s a taste of what Canon can do:

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)

4. Next Steps

After completing this section:

5. 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 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.

6. See Also

Table of contents