canon 0.1.3 → 0.1.5

data/README.adoc

@@ -1,219 +1,284 @@
-= Canon: Canonicalization for serialization formats
-
-A Ruby library for canonicalizing and pretty-printing XML, YAML, and JSON with
-RSpec matchers for equivalence testing.
-
+= Canon: Semantic comparison for serialization formats
+:toc:
+:toclevels: 2
 
 == Purpose
 
-This gem provides `Canon` which is a library for canonicalizing and
-pretty-printing various serialization formats (XML, YAML, JSON). It provides a
-standardized form suitable for comparison and testing.
-
-
-== Features
-
-XML canonicalization::
-Format XML documents according to the https://www.w3.org/TR/xml-c14n11/[W3C
-Canonicalized XML] format, with consistent indentation and ordering.
-
-YAML canonicalization::
-Format YAML documents with keys sorted alphabetically in a recursive manner at
-all levels of the YAML structure, with consistent indentation.
-
-JSON canonicalization::
-Format JSON documents with keys sorted alphabetically in a recursive manner at
-all levels of the JSON structure, with consistent indentation.
-
-RSpec matchers::
-Provides matchers for testing equivalence between serialized formats.
+Canon provides canonicalization, pretty-printing, and semantic comparison for
+serialization formats (XML, HTML, JSON, YAML). It produces standardized forms
+suitable for comparison, testing, digital signatures, and human-readable output.
 
-Unified interface::
-Single API for working with all three formats.
+Key features:
 
+* **Format support**: XML, HTML, JSON, YAML
+* **Canonicalization**: W3C XML C14N 1.1, sorted JSON/YAML keys
+* **Semantic comparison**: Compare meaning, not formatting
+* **Multiple interfaces**: Ruby API, CLI, RSpec matchers
+* **Smart diff output**: By-line or by-object modes with syntax highlighting
 
 == Installation
 
-Add this line to your application's Gemfile:
+Add to your application's Gemfile:
 
 [source,ruby]
 ----
 gem 'canon'
 ----
 
-And then execute:
+Then execute:
 
 [source,bash]
 ----
 $ bundle install
 ----
 
-Or install it yourself as:
+Or install directly:
 
 [source,bash]
 ----
 $ gem install canon
 ----
 
+== Quick start
 
-== Usage
+=== Format documents
 
-=== Formatting and canonicalization
+[source,ruby]
+----
+require 'canon'
 
-Canon provides a unified interface for formatting and canonicalizing XML,
-YAML, and JSON.
+# Canonical form (compact)
+Canon.format('<root><b>2</b><a>1</a></root>', :xml)
+# => "<root><a>1</a><b>2</b></root>"
 
-The `format` method is used to pretty-print and canonicalize the input data,
-with the arguments of the method taking the content and the format type as
-arguments.
+# Pretty-print (human-readable)
+require 'canon/pretty_printer/xml'
+Canon::Xml::PrettyPrinter.new(indent: 2).format(xml_input)
+----
 
-Syntax:
+=== Compare documents
 
 [source,ruby]
 ----
-# Generic method
-Canon.format({content}, {format})
+require 'canon/comparison'
 
-# Format-specific method
-Canon.format_{format}({content})
-----
+xml1 = '<root><a>1</a><b>2</b></root>'
+xml2 = '<root>  <b>2</b>  <a>1</a>  </root>'
 
-Where,
-
-`{content}`:: is the input string
-`{format}`:: is the format type, which can be `:xml`, `:yaml`, or `:json`.
+Canon::Comparison.equivalent?(xml1, xml2)
+# => true (semantically equivalent despite formatting differences)
+----
 
+=== Use in tests
 
-.Demonstration of formatting methods
-[example]
-====
 [source,ruby]
 ----
-require 'canon'
+require 'canon/rspec_matchers'
+
+RSpec.describe 'XML generation' do
+  it 'generates correct XML' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+  end
+end
+----
 
-# XML formatting
-xml_input = '<root><b>2</b><a>1</a></root>'
-formatted_xml = Canon.format(xml_input, :xml)
-# => Pretty-printed XML with consistent formatting
-# or
-formatted_xml = Canon.format_xml(xml_input)
+=== Command-line interface
 
-# YAML formatting
-yaml_input = "---\nz: 3\na: 1\nb: 2\n"
-formatted_yaml = Canon.format(yaml_input, :yaml)
-# => YAML with keys sorted alphabetically
-# or
-formatted_yaml = Canon.format_yaml(yaml_input)
+[source,bash]
+----
+# Format a file
+$ canon format input.xml --mode pretty
 
-# JSON formatting
-json_input = '{"z":3,"a":1,"b":2}'
-formatted_json = Canon.format(json_input, :json)
-# => Pretty-printed JSON with keys sorted alphabetically
-# or
-formatted_json = Canon.format_json(json_input)
+# Compare files
+$ canon diff file1.xml file2.xml --verbose
+
+# Get help
+$ canon help
 ----
-====
 
+== Documentation
 
-=== Parsing
+=== Using Canon
 
-Canon can also parse XML, YAML, and JSON strings into Ruby objects. The `parse`
-method takes the content and the format type as arguments, returning a Ruby
-object (Hash, Array, etc.) for YAML and JSON, or a Nokogiri XML document for XML.
+* **link:docs/RUBY_API[Ruby API]** - Using Canon from Ruby code
+* **link:docs/CLI[Command-line interface]** - CLI commands and options
+* **link:docs/RSPEC[RSpec matchers]** - Testing with Canon
 
-Syntax:
+=== Understanding Canon
 
-[source,ruby]
-----
-# Generic method
-Canon.parse({content}, {format})
+* **link:docs/MATCH_ARCHITECTURE[Match architecture]** - How comparison
+  works
+* **link:docs/FORMATS[Format support]** - XML, HTML, JSON, YAML details
+* **link:docs/MODES[Diff modes]** - By-line vs by-object comparison
 
-# Format-specific method
-Canon.parse_{format}({content})
-----
+=== Features
 
-Where,
+* **link:docs/PREPROCESSING[Preprocessing]** - Document normalization
+  options
+* **link:docs/MATCH_OPTIONS[Match options]** - Match dimensions and
+  profiles
+* **link:docs/DIFF_FORMATTING[Diff formatting]** - Customizing diff output
+* **link:docs/CHARACTER_VISUALIZATION[Character visualization]** -
+  Whitespace and special characters
+* **link:docs/INPUT_VALIDATION[Input validation]** - Error handling
 
-`{content}`:: is the input string
-`{format}`:: is the format type, which can be `:xml`, `:yaml`, or `:json`.
+=== Advanced topics
 
-.Demonstration of parsing methods
-[example]
-====
-[source,ruby]
-----
-# Parse XML
-xml_doc = Canon.parse(xml_input, :xml)
-xml_doc = Canon.parse_xml(xml_input)
-# => Nokogiri::XML::Document
+* **link:docs/VERBOSE[Verbose mode]** - Two-tier diff architecture
+* **link:docs/SEMANTIC_DIFF_REPORT[Semantic diff report]** - Diff report
+  format
+* **link:docs/NORMATIVE_INFORMATIVE_DIFFS[Normative vs informative diffs]** - Diff
+  classification
+* **link:docs/DIFF_ARCHITECTURE[Diff architecture]** - Technical pipeline
+  details
 
-# Parse YAML
-yaml_obj = Canon.parse(yaml_input, :yaml)
-yaml_obj = Canon.parse_yaml(yaml_input)
-# => Ruby object (Hash, Array, etc.)
+== Features
 
-# Parse JSON
-json_obj = Canon.parse(json_input, :json)
-json_obj = Canon.parse_json(json_input)
-# => Ruby object (Hash, Array, etc.)
-----
-====
+=== Canonicalization
+
+**XML**: W3C Canonical XML Version 1.1 specification with namespace
+declaration ordering, attribute ordering, character encoding normalization, and
+proper handling of xml:base, xml:lang, xml:space, and xml:id attributes.
+
+**HTML**: Consistent formatting for HTML 4/5 and XHTML with automatic detection
+and appropriate formatting rules.
+
+**JSON/YAML**: Alphabetically sorted keys at all levels with consistent
+formatting.
+
+=== Semantic comparison
+
+Compare documents based on meaning, not formatting:
 
+* Whitespace normalization options
+* Attribute/key order handling
+* Comment handling
+* Multiple match dimensions with behaviors
+* Predefined match profiles (strict, rendered, spec_friendly, content_only)
 
-=== RSpec matchers
+See link:docs/MATCH_OPTIONS[Match options] for details.
 
-The library provides RSpec matchers for testing equivalence between serialized
-formats:
+=== Smart diff output
+
+**By-line mode**: Traditional line-by-line diff with:
+
+* DOM-guided semantic matching for XML
+* Syntax-aware token highlighting
+* Context lines around changes
+* Whitespace visualization
+
+**By-object mode**: Tree-based semantic diff with:
+
+* Visual tree structure using box-drawing characters
+* Shows only what changed (additions, removals, modifications)
+* Color-coded output
+
+See link:docs/MODES[Diff modes] for details.
+
+=== Enhanced diff features
+
+* **Color-coded output**: Red (normative deletions), green (normative additions), yellow
+  (normative structure), cyan (informative diffs)
+* **Whitespace visualization**: Make invisible characters visible with CJK-safe
+  Unicode symbols
+* **Non-ASCII detection**: Warnings for unexpected Unicode characters
+* **Customizable**: Character maps, context lines, grouping options
+
+See link:docs/DIFF_FORMATTING[Diff formatting] and
+link:docs/CHARACTER_VISUALIZATION[Character visualization] for details.
+
+=== Input validation
+
+Comprehensive validation with clear error messages showing exact line and
+column numbers for syntax errors in XML, HTML, JSON, and YAML.
+
+See link:docs/INPUT_VALIDATION[Input validation] for details.
+
+== Examples
+
+=== Ruby API example
 
 [source,ruby]
 ----
-require 'rspec'
-require 'canon'
+require 'canon/comparison'
+
+# Compare with custom options
+Canon::Comparison.equivalent?(doc1, doc2,
+  match: {
+    text_content: :normalize,
+    structural_whitespace: :ignore,
+    comments: :ignore
+  },
+  verbose: true
+)
+----
 
-RSpec.describe 'Serialization tests' do
-  # Unified matcher with format parameter
-  it 'compares equivalent XML' do
-    xml1 = '<root><a>1</a><b>2</b></root>'
-    xml2 = '<root><b>2</b><a>1</a></root>'
-    expect(xml1).to be_serialization_equivalent_to(xml2, format: :xml)
-  end
+See link:docs/RUBY_API[Ruby API documentation].
 
-  it 'compares equivalent YAML' do
-    yaml1 = "---\na: 1\nb: 2\n"
-    yaml2 = "---\nb: 2\na: 1\n"
-    expect(yaml1).to be_serialization_equivalent_to(yaml2, format: :yaml)
-  end
+=== CLI example
 
-  it 'compares equivalent JSON' do
-    json1 = '{"a":1,"b":2}'
-    json2 = '{"b":2,"a":1}'
-    expect(json1).to be_serialization_equivalent_to(json2, format: :json)
-  end
+[source,bash]
+----
+# Compare with semantic diff
+$ canon diff file1.xml file2.xml \
+  --verbose \
+  --text-content normalize \
+  --structural-whitespace ignore
+----
+
+See link:docs/CLI[CLI documentation].
+
+=== RSpec example
+
+[source,ruby]
+----
+# Configure globally
+Canon::RSpecMatchers.configure do |config|
+  config.xml.match.profile = :spec_friendly
+  config.xml.diff.use_color = true
+end
 
-  # Format-specific matchers
-  it 'uses format-specific matchers' do
-    expect(xml1).to be_xml_equivalent_to(xml2)    # XML
-    expect(xml1).to be_analogous_with(xml2)       # XML (legacy matcher)
-    expect(yaml1).to be_yaml_equivalent_to(yaml2) # YAML
-    expect(json1).to be_json_equivalent_to(json2) # JSON
+# Use in tests
+RSpec.describe 'XML generation' do
+  it 'generates correct structure' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
   end
 end
 ----
 
+See link:docs/RSPEC[RSpec documentation].
+
+== Architecture
+
+Canon follows an orchestrator pattern with MECE (Mutually Exclusive,
+Collectively Exhaustive) principles:
+
+**Comparison module** (`Canon::Comparison`): Format detection, validation, and
+delegation to format-specific comparators (XML, HTML, JSON, YAML).
+
+**DiffFormatter module** (`Canon::DiffFormatter`): Diff mode detection and
+delegation to mode-specific formatters (by-line, by-object).
+
+**Three-phase comparison**:
+
+. **Preprocessing**: Optional document normalization (c14n, normalize, format)
+. **Semantic matching**: Configurable match dimensions with behaviors
+. **Diff rendering**: Formatted output with visualization
+
+See link:docs/MATCH_ARCHITECTURE[Match architecture] for details.
 
 == Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
+After checking out the repo, run `bin/setup` to install dependencies. Then run
 `rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
-
+prompt.
 
 == Contributing
 
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/lutaml/canon.
 
-
 == Copyright and license
 
-Copyright Ribose. https://opensource.org/licenses/BSD-2-Clause[BSD-2-Clause License].
+Copyright Ribose. https://opensource.org/licenses/BSD-2-Clause[BSD-2-Clause
+License].

data/_config.yml

@@ -0,0 +1,116 @@
+# Jekyll configuration for Canon documentation
+# Uses Just the Docs theme - https://just-the-docs.com/
+
+# Site settings
+title: Canon Documentation
+description: Semantic comparison for serialization formats (XML, HTML, JSON, YAML)
+url: https://lutaml.github.io
+baseurl: /canon
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs
+
+# AsciiDoc support
+asciidoc: {}
+asciidoctor:
+  attributes:
+    - idprefix=_
+    - source-highlighter=rouge
+    - icons=font
+    - experimental=''
+
+# Build settings
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+
+# Just the Docs theme configuration
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+
+# Navigation
+nav_sort: case_insensitive
+
+# Footer content
+footer_content: 'Copyright &copy; Ribose. <a href="https://opensource.org/licenses/BSD-2-Clause">BSD-2-Clause License</a>.'
+
+# Color scheme - use light mode
+color_scheme: light
+
+# Logo
+logo: false
+
+# Aux links for the upper right navigation
+aux_links:
+  "Canon on GitHub":
+    - "https://github.com/lutaml/canon"
+  "Report Issue":
+    - "https://github.com/lutaml/canon/issues"
+
+# Aux links configuration
+aux_links_new_tab: true
+
+# Heading anchors
+heading_anchors: true
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Collections - for organizing documentation
+collections:
+  docs:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Collection defaults
+defaults:
+  - scope:
+      path: "docs"
+      type: "docs"
+    values:
+      layout: "default"
+      nav_exclude: false
+
+# Only process documentation AsciiDoc files
+include:
+  - index.adoc
+
+# Exclude everything except docs directory
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - Gemfile.docs
+  - README.adoc
+  - node_modules
+  - vendor
+  - lib
+  - spec
+  - bin
+  - exe
+  - pkg
+  - sig
+  - old-docs
+  - .rspec
+  - .rubocop.yml
+  - .rubocop_todo.yml
+  - .gitignore
+  - Rakefile
+  - canon.gemspec
+  - .git
+  - .github
+  - "*.md"
+  - "*.swp"
+  - "*.tmp"
+  - "**/*.md"
+  - "!docs/**"
+
+# Keep only AsciiDoc files in docs directory
+keep_files:
+  - "docs/*.adoc"

data/docs/ADVANCED_TOPICS.adoc

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Advanced Topics
+nav_order: 5
+has_children: true
+---
+= Advanced topics
+
+For developers and advanced users:
+
+* **link:VERBOSE[Verbose mode]** - Two-tier diff output architecture
+* **link:SEMANTIC_DIFF_REPORT[Semantic diff report]** - Detailed report
+format
+* **link:NORMATIVE_INFORMATIVE_DIFFS[Normative vs informative diffs]** - Diff
+classification
+* **link:DIFF_ARCHITECTURE[Diff architecture]** - Six-layer technical
+pipeline
+
+These documents cover Canon's internal architecture and advanced features for
+developers extending or maintaining Canon.

data/docs/BASIC_USAGE.adoc

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Basic Usage
+nav_order: 2
+has_children: true
+---
+= Basic usage
+
+Choose your interface for working with Canon:
+
+* **link:RUBY_API[Ruby API]** - Using Canon from Ruby code
+* **link:CLI[Command-line interface]** - Terminal commands and options
+* **link:RSPEC[RSpec matchers]** - Testing with Canon in RSpec
+
+These guides provide practical examples and complete API reference for each
+interface.