Add opt-in binary string diff support

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Features
+
+- Add opt-in binary string diff support. [#301](https://github.com/splitwise/super_diff/pull/301) by [@gschlager](https://github.com/gschlager)
+
 ### Other changes
 
 - Add max major version constraints to dependencies. [#296](https://github.com/splitwise/super_diff/pull/296)

README.md

@@ -92,6 +92,17 @@ you'd get this instead:
 
 [user-docs]: ./docs/users/getting-started.md
 
+### Optional Extensions
+
+If you need diffs for binary strings (`Encoding::ASCII_8BIT`),
+require the binary string integration:
+
+```ruby
+require "super_diff/binary_string"
+```
+
+This enables hex-dump diffs and keeps binary data out of the expectation text.
+
 ## Support
 
 My goal for this library is to improve your development experience.

docs/users/getting-started.md

@@ -86,6 +86,18 @@ such as matchers.
 
 You can now continue on to [customizing SuperDiff](./customization.md).
 
+## Binary Strings
+
+SuperDiff can diff binary strings (`Encoding::ASCII_8BIT`) using a hex-dump
+format and a binary-safe inspection label.
+To enable this, add:
+
+```ruby
+require "super_diff/binary_string"
+```
+
+You can create binary strings with `String#b` or by forcing the encoding.
+
 ## Using parts of SuperDiff directly
 
 Although SuperDiff is primarily designed to integrate with RSpec,

lib/super_diff/binary_string.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'super_diff/binary_string/differs'
+require 'super_diff/binary_string/inspection_tree_builders'
+require 'super_diff/binary_string/operation_trees'
+require 'super_diff/binary_string/operation_tree_builders'
+require 'super_diff/binary_string/operation_tree_flatteners'
+
+module SuperDiff
+  module BinaryString
+    def self.applies_to?(*values)
+      values.all? { |value| value.is_a?(::String) && value.encoding == Encoding::ASCII_8BIT }
+    end
+
+    SuperDiff.configure do |config|
+      config.prepend_extra_differ_classes(Differs::BinaryString)
+      config.prepend_extra_inspection_tree_builder_classes(
+        InspectionTreeBuilders::BinaryString
+      )
+    end
+  end
+end

lib/super_diff/binary_string/differs.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module Differs
+      autoload(
+        :BinaryString,
+        'super_diff/binary_string/differs/binary_string'
+      )
+    end
+  end
+end

lib/super_diff/binary_string/differs/binary_string.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module Differs
+      class BinaryString < Core::AbstractDiffer
+        def self.applies_to?(expected, actual)
+          SuperDiff::BinaryString.applies_to?(expected, actual)
+        end
+
+        protected
+
+        def operation_tree_builder_class
+          OperationTreeBuilders::BinaryString
+        end
+      end
+    end
+  end
+end

lib/super_diff/binary_string/inspection_tree_builders.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module InspectionTreeBuilders
+      autoload(
+        :BinaryString,
+        'super_diff/binary_string/inspection_tree_builders/binary_string'
+      )
+    end
+  end
+end

lib/super_diff/binary_string/inspection_tree_builders/binary_string.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module InspectionTreeBuilders
+      class BinaryString < Core::AbstractInspectionTreeBuilder
+        def self.applies_to?(value)
+          SuperDiff::BinaryString.applies_to?(value)
+        end
+
+        def call
+          Core::InspectionTree.new do |t|
+            t.add_text "<binary string (#{object.bytesize} bytes)>"
+          end
+        end
+      end
+    end
+  end
+end

lib/super_diff/binary_string/operation_tree_builders.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module OperationTreeBuilders
+      autoload(
+        :BinaryString,
+        'super_diff/binary_string/operation_tree_builders/binary_string'
+      )
+    end
+  end
+end

lib/super_diff/binary_string/operation_tree_builders/binary_string.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module OperationTreeBuilders
+      class BinaryString < Basic::OperationTreeBuilders::MultilineString
+        BYTES_PER_LINE = 16
+        private_constant :BYTES_PER_LINE
+
+        def self.applies_to?(expected, actual)
+          SuperDiff::BinaryString.applies_to?(expected, actual)
+        end
+
+        def initialize(*args)
+          args.first[:expected] = binary_to_hex(args.first[:expected])
+          args.first[:actual] = binary_to_hex(args.first[:actual])
+
+          super
+        end
+
+        protected
+
+        def build_operation_tree
+          OperationTrees::BinaryString.new([])
+        end
+
+        private
+
+        def split_into_lines(string)
+          super.map { |line| line.delete_suffix("\n") }.reject(&:empty?)
+        end
+
+        def binary_to_hex(data)
+          data
+            .each_byte
+            .each_slice(BYTES_PER_LINE)
+            .with_index
+            .map { |bytes, index| format_hex_line(index * BYTES_PER_LINE, bytes) }
+            .join("\n")
+        end
+
+        def format_hex_line(offset, bytes)
+          hex_pairs = bytes
+                      .map { |b| format('%02x', b) }
+                      .each_slice(2)
+                      .map(&:join)
+                      .join(' ')
+
+          ascii = bytes.map { |b| printable_char(b) }.join
+
+          format('%<offset>08x: %<hex>-39s  %<ascii>s', offset:, hex: hex_pairs, ascii:)
+        end
+
+        def printable_char(byte)
+          byte >= 32 && byte < 127 ? byte.chr : '.'
+        end
+      end
+    end
+  end
+end

lib/super_diff/binary_string/operation_tree_flatteners.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module OperationTreeFlatteners
+      autoload(
+        :BinaryString,
+        'super_diff/binary_string/operation_tree_flatteners/binary_string'
+      )
+    end
+  end
+end

lib/super_diff/binary_string/operation_tree_flatteners/binary_string.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module OperationTreeFlatteners
+      class BinaryString < Core::AbstractOperationTreeFlattener
+        def build_tiered_lines
+          operation_tree.map do |operation|
+            Core::Line.new(
+              type: operation.name,
+              indentation_level: indentation_level,
+              value: operation.value
+            )
+          end
+        end
+      end
+    end
+  end
+end

lib/super_diff/binary_string/operation_trees.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module OperationTrees
+      autoload(
+        :BinaryString,
+        'super_diff/binary_string/operation_trees/binary_string'
+      )
+    end
+  end
+end

lib/super_diff/binary_string/operation_trees/binary_string.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SuperDiff
+  module BinaryString
+    module OperationTrees
+      class BinaryString < Core::AbstractOperationTree
+        def self.applies_to?(value)
+          SuperDiff::BinaryString.applies_to?(value)
+        end
+
+        protected
+
+        def operation_tree_flattener_class
+          OperationTreeFlatteners::BinaryString
+        end
+      end
+    end
+  end
+end

lib/super_diff/rspec/differ.rb

@@ -42,10 +42,16 @@ def comparing_proc_values?
       end
 
       def comparing_singleline_strings?
+        return false if comparing_binary_strings?
+
         expected.is_a?(String) && actual.is_a?(String) &&
           !expected.include?("\n") && !actual.include?("\n")
       end
 
+      def comparing_binary_strings?
+        defined?(BinaryString) && BinaryString.applies_to?(expected, actual)
+      end
+
       def helpers
         @helpers ||= RSpecHelpers.new
       end

spec/integration/rspec/binary_string_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'super_diff/binary_string'
+
+RSpec.describe 'Integration with binary strings', type: :integration do
+  context 'when comparing two different binary strings' do
+    it 'produces the correct failure message' do
+      as_both_colored_and_uncolored do |color_enabled|
+        snippet = <<~TEST.strip
+          require 'super_diff/binary_string'
+          actual = "Hello".b
+          expected = "World".b
+          expect(actual).to eq(expected)
+        TEST
+        program =
+          make_plain_test_program(snippet, color_enabled: color_enabled)
+
+        expected_output =
+          build_expected_output(
+            color_enabled: color_enabled,
+            snippet: 'expect(actual).to eq(expected)',
+            expectation:
+              proc do
+                line do
+                  plain 'Expected '
+                  actual '<binary string (5 bytes)>'
+                  plain ' to eq '
+                  expected '<binary string (5 bytes)>'
+                  plain '.'
+                end
+              end,
+            diff:
+              proc do
+                expected_line '- 00000000: 576f 726c 64                             World'
+                actual_line '+ 00000000: 4865 6c6c 6f                             Hello'
+              end
+          )
+
+        expect(program).to produce_output_when_run(expected_output).in_color(
+          color_enabled
+        )
+      end
+    end
+  end
+
+  context 'when comparing binary strings spanning multiple lines' do
+    it 'produces a multi-line hex dump diff' do
+      as_both_colored_and_uncolored do |color_enabled|
+        snippet = <<~TEST.strip
+          require 'super_diff/binary_string'
+          actual = ("A" * 20).b
+          expected = ("A" * 16 + "B" * 4).b
+          expect(actual).to eq(expected)
+        TEST
+        program =
+          make_plain_test_program(snippet, color_enabled: color_enabled)
+
+        expected_output =
+          build_expected_output(
+            color_enabled: color_enabled,
+            snippet: 'expect(actual).to eq(expected)',
+            expectation:
+              proc do
+                line do
+                  plain 'Expected '
+                  actual '<binary string (20 bytes)>'
+                  plain ' to eq '
+                  expected '<binary string (20 bytes)>'
+                  plain '.'
+                end
+              end,
+            diff:
+              proc do
+                plain_line '  00000000: 4141 4141 4141 4141 4141 4141 4141 4141  AAAAAAAAAAAAAAAA'
+                expected_line '- 00000010: 4242 4242                                BBBB'
+                actual_line '+ 00000010: 4141 4141                                AAAA'
+              end
+          )
+
+        expect(program).to produce_output_when_run(expected_output).in_color(
+          color_enabled
+        )
+      end
+    end
+  end
+end