Add opt-in binary string diff support

Add a `SuperDiff::BinaryString` extension that renders `ASCII-8BIT` strings as hex dumps. Users opt-in by requiring the module:

```
require 'super_diff/binary_string'
```

Includes a dedicated differ, inspection tree builder, operation tree builder/tree/flattener, and updates SuperDiff::RSpec::Differ to allow diffs for binary strings (skipping the single-line string short-
circuit).

Hex dumps use 16 bytes per line with offset, hex pairs, and ASCII representation (xxd-style output).

Author: gschlager

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,28 @@
+# 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_operation_tree_builder_classes(
+        OperationTreeBuilders::BinaryString
+      )
+      config.prepend_extra_operation_tree_classes(
+        OperationTrees::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,66 @@
+# 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
+
+        # Prevent creation of BinaryOperation objects which the flattener
+        # cannot handle
+        def should_compare?(_operation, _next_operation)
+          false
+        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