Class: Canon::Comparison::ComparisonResult

Inherits:
Object
  • Object
show all
Defined in:
lib/canon/comparison/comparison_result.rb

Overview

Encapsulates the result of a comparison operation Provides methods to query equivalence based on normative diffs

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(differences:, preprocessed_strings:, format:, html_version: nil, match_options: nil, algorithm: :dom, original_strings: nil, parse_errors_expected: nil, parse_errors_received: nil) ⇒ ComparisonResult

Returns a new instance of ComparisonResult.

Parameters:

  • differences (Array<DiffNode>) —

    Array of difference nodes

  • preprocessed_strings (Array<String, String>, Proc) —

    Pre-processed content for display, or a Proc returning the Array (materialized on first read)

  • format (Symbol) —

    Format type (:xml, :html, :json, :yaml)

  • html_version (Symbol, nil) (defaults to: nil) —

    HTML version (:html4 or :html5) for HTML format only

  • match_options (Hash, nil) (defaults to: nil) —

    Resolved match options used for comparison

  • algorithm (Symbol) (defaults to: :dom) —

    Diff algorithm used (:dom or :semantic)

  • original_strings (Array<String, String>, nil) (defaults to: nil) —

    Original unprocessed content for line diff

  • parse_errors_expected (Array<String>, nil) (defaults to: nil) —

    Parser errors from the expected side

  • parse_errors_received (Array<String>, nil) (defaults to: nil) —

    Parser errors from the received side



23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/canon/comparison/comparison_result.rb', line 23

def initialize(differences:, preprocessed_strings:, format:,
html_version: nil, match_options: nil, algorithm: :dom, original_strings: nil,
parse_errors_expected: nil, parse_errors_received: nil)
  @differences = differences
  @preprocessed_strings = preprocessed_strings
  @original_strings = original_strings
  @format = format
  @html_version = html_version
  @match_options = match_options
  @algorithm = algorithm
  @parse_errors_expected = Array(parse_errors_expected)
  @parse_errors_received = Array(parse_errors_received)
end

Instance Attribute Details

#algorithm ⇒ Object (readonly)

Returns the value of attribute algorithm.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def algorithm
  @algorithm
end

#differences ⇒ Object (readonly)

Returns the value of attribute differences.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def differences
  @differences
end

#format ⇒ Object (readonly)

Returns the value of attribute format.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def format
  @format
end

#html_version ⇒ Object (readonly)

Returns the value of attribute html_version.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def html_version
  @html_version
end

#match_options ⇒ Object (readonly)

Returns the value of attribute match_options.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def match_options
  @match_options
end

#parse_errors_expected ⇒ Object (readonly)

Returns the value of attribute parse_errors_expected.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def parse_errors_expected
  @parse_errors_expected
end

#parse_errors_received ⇒ Object (readonly)

Returns the value of attribute parse_errors_received.



8
9
10
 
# File 'lib/canon/comparison/comparison_result.rb', line 8

def parse_errors_received
  @parse_errors_received
end

Instance Method Details

#diff(use_color: true, context_lines: 3, diff_grouping_lines: nil, show_diffs: :all, diff_mode: :separate, legacy_terminal: false) ⇒ String

Generate formatted diff output

Parameters:

  • use_color (Boolean) (defaults to: true) —

    Whether to use ANSI color codes

  • context_lines (Integer) (defaults to: 3) —

    Number of context lines to show

  • diff_grouping_lines (Integer) (defaults to: nil) —

    Maximum gap for grouping diffs

  • show_diffs (Symbol) (defaults to: :all) —

    Which diffs to show (:all, :normative, :informative)

  • diff_mode (Symbol) (defaults to: :separate) —

    Diff display mode (:separate, :inline)

  • legacy_terminal (Boolean) (defaults to: false) —

    Force legacy mode (no ANSI, separate-line only)

Returns:

  • (String) —

    Formatted diff output



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/canon/comparison/comparison_result.rb', line 158

def diff(use_color: true, context_lines: 3, diff_grouping_lines: nil,
show_diffs: :all, diff_mode: :separate, legacy_terminal: false)
  formatter = Canon::DiffFormatter.new(
    use_color: use_color,
    mode: :by_line,
    context_lines: context_lines,
    diff_grouping_lines: diff_grouping_lines,
    show_diffs: show_diffs,
    diff_mode: diff_mode,
    legacy_terminal: legacy_terminal,
  )

  # Pass self (ComparisonResult) so formatter can check equivalent? status
  formatter.format(
    self,
    @format,
    doc1: preprocessed_strings[0],
    doc2: preprocessed_strings[1],
    html_version: @html_version,
  )
end

#equivalent? ⇒ Boolean

Check if documents are semantically equivalent (no normative diffs)

Returns:

  • (Boolean) —

    true if no normative differences present



70
71
72
 
# File 'lib/canon/comparison/comparison_result.rb', line 70

def equivalent?
  !has_normative_diffs?
end

#has_informative_diffs? ⇒ Boolean

Check if there are any informative (textual-only) differences

Returns:

  • (Boolean) —

    true if at least one informative diff exists



94
95
96
97
98
 
# File 'lib/canon/comparison/comparison_result.rb', line 94

def has_informative_diffs?
  @differences.any? do |diff|
    diff.is_a?(Canon::Diff::DiffNode) && diff.informative?
  end
end

#has_normative_diffs? ⇒ Boolean

Check if there are any normative (semantic) differences Includes both DiffNode objects marked as normative AND legacy Hash differences (which represent structural differences like element name mismatches)

Returns:

  • (Boolean) —

    true if at least one normative diff exists



79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/canon/comparison/comparison_result.rb', line 79

def has_normative_diffs?
  @differences.any? do |diff|
    # DiffNode objects - check if marked normative
    if diff.is_a?(Canon::Diff::DiffNode)
      diff.normative?
    # Legacy Hash format - always considered normative (structural differences)
    else
      diff.is_a?(Hash)
    end
  end
end

#informative_differences ⇒ Array<DiffNode>

Get all informative differences

Returns:

  • (Array<DiffNode>) —

    Informative differences only



112
113
114
115
116
 
# File 'lib/canon/comparison/comparison_result.rb', line 112

def informative_differences
  @differences.select do |diff|
    diff.is_a?(Canon::Diff::DiffNode) && diff.informative?
  end
end

#normative_differences ⇒ Array<DiffNode>

Get all normative differences

Returns:

  • (Array<DiffNode>) —

    Normative differences only



103
104
105
106
107
 
# File 'lib/canon/comparison/comparison_result.rb', line 103

def normative_differences
  @differences.select do |diff|
    diff.is_a?(Canon::Diff::DiffNode) && diff.normative?
  end
end

#operations ⇒ Array<Operation>

Get tree diff operations (only available when diff_algorithm: :semantic)

Returns:

  • (Array<Operation>) —

    Array of tree diff operations



121
122
123
 
# File 'lib/canon/comparison/comparison_result.rb', line 121

def operations
  @match_options&.[](:tree_diff_operations) || []
end

#original_strings ⇒ Array<String, String>

Unprocessed input strings; falls back to the preprocessed pair when the comparator did not provide originals.

Returns:

  • (Array<String, String>) 


55
56
57
 
# File 'lib/canon/comparison/comparison_result.rb', line 55

def original_strings
  @original_strings || preprocessed_strings
end

#parse_errors? ⇒ Boolean

Whether either side reported parse errors. Used by the diff formatter to decide whether to render the parse-error banner.

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/canon/comparison/comparison_result.rb', line 63

def parse_errors?
  @parse_errors_expected.any? || @parse_errors_received.any?
end

#preprocessed_strings ⇒ Array<String, String>

Display strings for the compared inputs. When the comparator supplied a builder Proc (the display strings require serializing both parsed documents), materialization is deferred to the first read: by_object consumers never pay it, by_line and preprocessed display trigger it exactly once.

Returns:

  • (Array<String, String>) 


44
45
46
47
48
49
 
# File 'lib/canon/comparison/comparison_result.rb', line 44

def preprocessed_strings
  unless @preprocessed_strings.is_a?(Array)
    @preprocessed_strings = @preprocessed_strings.call
  end
  @preprocessed_strings
end

#summary ⇒ String

Generate a human-readable summary of the first difference.

When documents are equivalent, returns "Equivalent". When they differ, returns a single-line string with the first normative (or first informative) difference location and reason.

Returns:

  • (String) —

    Summary string



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/canon/comparison/comparison_result.rb', line 132

def summary
  return "Equivalent" if equivalent?

  diff = normative_differences.first || informative_differences.first ||
         @differences.first # rubocop:disable Layout/MultilineOperationIndentation

  return "Not equivalent" unless diff

  if diff.is_a?(Canon::Diff::DiffNode)
    summarize_diff_node(diff)
  elsif diff.is_a?(Hash)
    summarize_legacy_hash(diff)
  else
    "Not equivalent"
  end
end