canon 0.1.8 → 0.1.9

data/old-docs/STRING_COMPARE.adoc

@@ -1,345 +0,0 @@
-= String Comparison in Canon
-:toc:
-:toclevels: 3
-
-== General
-
-Canon provides advanced string comparison capabilities with character-level visualization and diff rendering. This feature is particularly useful for:
-
-* Comparing strings with invisible whitespace differences (spaces, tabs, trailing newlines)
-* Detecting Unicode differences (non-breaking spaces, zero-width characters, etc.)
-* Visualizing multi-line string differences with context
-* Identifying trailing newline differences in text output
-
-== Character Visualization
-
-Canon automatically visualizes invisible and special characters to make differences clear:
-
-[cols="2,3,2",options="header"]
-|===
-|Character
-|Description
-|Visualization
-
-|Space (U+0020)
-|Regular space
-|`░`
-
-|Tab (U+0009)
-|Tab character
-|`⇥`
-
-|Non-breaking space (U+00A0)
-|Non-breaking space
-|`␣`
-
-|Zero-width space (U+200B)
-|Zero-width space
-|`→`
-
-|Other invisible characters
-|Various Unicode invisibles
-|See Unicode legend in output
-|===
-
-== Usage in RSpec
-
-=== Auto-detection with `be_equivalent_to`
-
-The `be_equivalent_to` matcher automatically detects the format (XML, JSON, YAML, or string) and uses the appropriate comparison mode.
-
-.Auto-detecting string mode
-[source,ruby]
-----
-RSpec.describe "String comparison" do
-  it "auto-detects string format" do
-    actual = "Hello World"
-    expected = "Hello Universe"
-
-    expect(actual).to be_equivalent_to(expected)
-    # Automatically uses STRING mode for plain text
-  end
-end
-----
-
-=== Explicit string mode with `be_string_equivalent_to`
-
-For explicit string comparison, use the `be_string_equivalent_to` matcher.
-
-.Basic string comparison
-[source,ruby]
-----
-RSpec.describe "String comparison" do
-  it "compares strings exactly" do
-    expect("Hello World").to be_string_equivalent_to("Hello World")
-  end
-
-  it "detects differences" do
-    expect("Hello World").not_to be_string_equivalent_to("Hello Universe")
-  end
-end
-----
-
-=== Whitespace differences
-
-.Detecting extra spaces
-[source,ruby]
-----
-it "detects extra spaces" do
-  actual = "Hello World"
-  expected = "Hello  World"  # Two spaces
-
-  expect(actual).not_to be_string_equivalent_to(expected)
-end
-----
-
-When this test fails, the output shows:
-
-----
-expected STRING to be equivalent
-
-Line-by-line diff (STRING mode):
-   1|   1- | Hello░World
-    |   1+ | Hello░░World
-----
-
-=== Trailing newline differences
-
-.Detecting trailing newlines
-[source,ruby]
-----
-it "detects trailing newline" do
-  actual = "data:image/png;base64,abc123"
-  expected = "data:image/png;base64,abc123\n"
-
-  expect(actual).not_to be_string_equivalent_to(expected)
-end
-----
-
-When this test fails, the output shows two separate lines:
-
-----
-expected STRING to be equivalent
-
-Line-by-line diff (STRING mode):
-   1|   1  | data:image/png;base64,abc123
-    |   2+ |
-----
-
-The empty line on line 2 (shown in green with `+`) represents the trailing newline character.
-
-=== Unicode character differences
-
-.Detecting Unicode differences
-[source,ruby]
-----
-it "detects non-breaking space vs regular space" do
-  actual = "Hello World"
-  expected = "Hello\u00A0World"  # Non-breaking space
-
-  expect(actual).not_to be_string_equivalent_to(expected)
-end
-----
-
-When this test fails, the output includes a Unicode legend:
-
-----
-expected STRING to be equivalent
-
-Character Visualization Legend:
-  ░ = U+0020 (Space)
-  ␣ = U+00A0 (Non-breaking space)
-
-Line-by-line diff (STRING mode):
-   1|   1- | Hello░World
-    |   1+ | Hello␣World
-----
-
-=== Multi-line string differences
-
-.Comparing multi-line strings
-[source,ruby]
-----
-it "shows line-by-line diff for multi-line strings" do
-  actual = <<~TEXT
-    Line 1
-    Line 2
-    Line 3
-  TEXT
-
-  expected = <<~TEXT
-    Line 1
-    Line 2 Modified
-    Line 3
-  TEXT
-
-  expect(actual).not_to be_string_equivalent_to(expected)
-end
-----
-
-Output shows context around the changed line:
-
-----
-expected STRING to be equivalent
-
-Line-by-line diff (STRING mode):
-   1|   1  | Line 1
-   2|   2- | Line 2
-    |   2+ | Line 2 Modified
-   3|   3  | Line 3
-----
-
-== Usage in CLI
-
-=== Comparing string files
-
-.Using the diff command
-[source,bash]
-----
-canon diff actual.txt expected.txt --format string
-----
-
-.Output
-----
-Line-by-line diff (STRING mode):
-   1|   1  | Hello World
-   2|   2- | Line with spaces
-    |   2+ | Line with  spaces
-   3|   3  | Final line
-----
-
-=== Format auto-detection
-
-If you don't specify `--format`, Canon will auto-detect the format based on file content:
-
-[source,bash]
-----
-canon diff actual.txt expected.txt
-# Auto-detects as string if content isn't XML/JSON/YAML
-----
-
-== Usage in API
-
-=== Using DiffFormatter directly
-
-.Programmatic string comparison
-[source,ruby]
-----
-require 'canon/diff_formatter'
-
-actual = "Hello World"
-expected = "Hello  World"  # Two spaces
-
-formatter = Canon::DiffFormatter.new(
-  use_color: true,
-  mode: :by_line,
-  context_lines: 3
-)
-
-diff = formatter.format([], :string,
-                        doc1: actual,
-                        doc2: expected)
-puts diff
-----
-
-.Output
-----
-Line-by-line diff (STRING mode):
-   1|   1- | Hello░World
-    |   1+ | Hello░░World
-----
-
-=== Using Canon.format for canonicalization
-
-Note: For strings, Canon does not perform canonicalization (no formatting changes are applied). The string is compared exactly as-is.
-
-.String comparison example
-[source,ruby]
-----
-require 'canon'
-
-actual = "Hello World"
-expected = "Hello World"
-
-# Strings are compared as-is (no canonicalization)
-result = Canon.format(actual, :string)
-# => "Hello World"
-
-result == expected  # => true
-----
-
-== Configuration
-
-=== Customizing character visualization
-
-You can customize how characters are visualized by configuring the visualization map:
-
-.Customizing character map
-[source,ruby]
-----
-Canon::RSpecMatchers.configure do |config|
-  config.use_color = true
-  config.context_lines = 3
-  config.diff_mode = :by_line
-end
-----
-
-=== Color output
-
-Color output is enabled by default in RSpec. To disable:
-
-.Disabling colors
-[source,ruby]
-----
-Canon::RSpecMatchers.configure do |config|
-  config.use_color = false
-end
-----
-
-== Advanced Features
-
-=== Trailing newline detection
-
-Canon properly handles trailing newlines by preserving them during line splitting. This ensures that strings like:
-
-* `"text"` (no trailing newline)
-* `"text\n"` (with trailing newline)
-
-Are shown as different, with the trailing newline visualized as an empty line in the diff output.
-
-=== Context lines
-
-By default, Canon shows 3 lines of context around changes. This can be configured:
-
-.Adjusting context lines
-[source,ruby]
-----
-Canon::RSpecMatchers.configure do |config|
-  config.context_lines = 5  # Show 5 lines of context
-end
-----
-
-== Technical Implementation
-
-=== Line splitting
-
-Canon uses `split("\n", -1)` to preserve trailing empty strings, ensuring that:
-
-[source,ruby]
-----
-"abc\n".split("\n", -1)  # => ["abc", ""]
-"abc".split("\n", -1)     # => ["abc"]
-----
-
-This allows proper detection and visualization of trailing newlines.
-
-=== Character visualization map
-
-The character visualization is configurable via `lib/canon/diff_formatter/character_map.yml`. See link:VISUALIZATION_MAP[Visualization Map Documentation] for details on customizing character representations.
-
-== See Also
-
-* link:README[Canon README] - General Canon documentation
-* link:VISUALIZATION_MAP[Visualization Map] - Character visualization customization
-* link:DIFF_PARAMETERS[Diff Parameters] - Diff formatting options
-* link:MATCHER_BEHAVIOR[Matcher Behavior] - RSpec matcher details