rbindiff 2025.6.21

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5478fd0461693bf21baa0ba67a10315193e2793de656674c23ecc9af0636a438
+  data.tar.gz: 55a25484dc6e29a307365c0e93b210ae78ee0554ee040e1a5a2284c85303bba1
+SHA512:
+  metadata.gz: aea6f0cca7edfc1ac9066d87c6607f706c821a19324ab88daec3bebbb987382defe7f70ef1f833783014eaa891805bbcf2af65b10de9db74d920fccc600ba944
+  data.tar.gz: f19a8213d5adf16be22672bf7eed12e4cfeee6114106aac86049fee534b3c8fe3dc4773a9b99dc60a9bb937ae174de9584c2c21e7caf78ad5c01a771a8cc92ce

data/README.md

@@ -0,0 +1,128 @@
+# 🌟 Welcome to **rbindiff** – A Binary File Comparison Tool! 🌟
+
+You're about to build a powerful and useful gem called `rbindiff` that compares binary files byte by byte, highlights differences, and calculates similarity ratios. This README will guide you through the project structure, how it works, and how others can install and use it.
+
+---
+
+## 🚀 What is rbindiff?
+
+**rbindiff** stands for "Ruby Binary Diff". It's a command-line tool written in Ruby that:
+
+- Compares two binary files byte-by-byte.
+- Outputs a human-readable summary of:
+  - Ranges where the files are **identical**
+  - Ranges where they **differ**, with short hex representations
+  - Extra content at the end if one file is longer than the other
+- Calculates **similarity percentage** based on matching bytes.
+
+---
+
+## 🔧 Installation
+
+```bash
+gem install rbindiff
+```
+
+Once installed, you'll have access to the `rbindiff` executable in your terminal.
+
+---
+
+## 📦 Usage
+
+```bash
+rbindiff <file1> <file2>
+```
+
+### Example:
+
+```bash
+rbindiff image1.png image2.png
+```
+
+---
+
+## ✨ Sample Output
+
+```
+Comparing: image1.png vs image2.png
+
+[Identical] Bytes 0x0000 to 0x00FF (256 bytes)
+[Different] Bytes 0x0100 to 0x010F (16 bytes)
+File1: 48 65 6C 6C 6F 20 77 6F ... 6E 67 20 77 6F 72 6C 64
+File2: 48 65 6C 6C 6F 20 77 6F ... 6E 67 20 57 4F 52 4C 44
+
+[Identical] Bytes 0x0110 to 0x01FF (240 bytes)
+[Extra] File2 has 32 extra bytes from 0x0200 to 0x021F
+
+Similarity: 92.5% (same bytes) / 89.1% (relative to total lengths)
+```
+
+---
+
+## 🛠️ Features
+
+✅ Byte-level comparison  
+✅ Human-readable output  
+✅ Hex dump of differing regions (with ellipsis)  
+✅ Similarity percentages  
+✅ Supports files of different lengths  
+✅ Terminal-safe formatting  
+
+---
+
+## 📁 Project Structure
+
+```
+rbindiff/
+├── bin/
+│   └── rbindiff        # Executable script
+├── lib/
+│   └── rbindiff.rb     # Main logic
+├── rbindiff.gemspec
+├── Gemfile
+├── README.md           # You're reading this!
+└── .gitignore
+```
+
+---
+
+## 📝 How It Works
+
+The core algorithm works like this:
+
+1. Open both files as binary streams.
+2. Read them into byte arrays.
+3. Compare byte-by-byte up to the minimum length.
+4. Track ranges of identical or differing bytes.
+5. If one file is longer, record the extra part.
+6. Print the result with range info, diffs, and similarity ratio.
+
+---
+
+## 🧮 Similarity Calculation
+
+There are two values:
+
+- `% Matched`: `(Same bytes) / min(file1.size, file2.size)`
+- `% Relative`: `(Same bytes) / max(file1.size, file2.size)`
+
+This gives an idea of how similar the common parts are, and how much of the larger file matches.
+
+---
+
+## 🎨 Color & Formatting (Optional)
+
+If you want to enhance user experience later:
+
+- Use ANSI escape codes to color-code differences
+- Add progress bar or spinner for large files
+
+---
+
+## 🙌 You've Got This!
+
+Building tools like `rbindiff` helps developers debug binaries, reverse-engineer files, and understand low-level data formats. Your work could help many people — including future YOU.
+
+Keep going! You're doing great 💪
+
+Let me know when you're ready to write the code — I'd love to help you implement each part step by step!

data/bin/rbindiff

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/rbindiff'
+
+RBinDiff.run(ARGV)

data/lib/rbindiff.rb

@@ -0,0 +1,149 @@
+# lib/rbindiff.rb
+
+module RBinDiff
+  def self.run(args)
+    if args.size != 2
+      puts "Usage: rbindiff <file1> <file2>"
+      exit 1
+    end
+
+    file1, file2 = args
+
+    unless File.exist?(file1) && File.readable?(file1)
+      puts "Error: Cannot read file1 '#{file1}'"
+      exit 1
+    end
+
+    unless File.exist?(file2) && File.readable?(file2)
+      puts "Error: Cannot read file2 '#{file2}'"
+      exit 1
+    end
+
+    content1 = File.binread(file1)
+    content2 = File.binread(file2)
+
+    compare_and_report(content1, content2)
+  end
+
+  def self.compare_and_report(content1, content2)
+    offset = 0
+    results = []
+    max_length = [content1.bytesize, content2.bytesize].max
+    chunk_size = 1024 * 1024 # 每1MB更新一次进度
+
+    print "Progress: [............] 0%\r"
+
+    while offset < max_length
+      b1 = offset < content1.bytesize ? content1.getbyte(offset) : nil
+      b2 = offset < content2.bytesize ? content2.getbyte(offset) : nil
+      same = b1 == b2
+
+      range_start = offset
+
+      if same
+        while offset < max_length
+          b1 = offset < content1.bytesize ? content1.getbyte(offset) : nil
+          b2 = offset < content2.bytesize ? content2.getbyte(offset) : nil
+          break unless b1 == b2
+          offset += 1
+        end
+      else
+        while offset < max_length
+          b1 = offset < content1.bytesize ? content1.getbyte(offset) : nil
+          b2 = offset < content2.bytesize ? content2.getbyte(offset) : nil
+          break if b1 == b2
+          offset += 1
+        end
+      end
+
+      results << {
+        same: same,
+        start: range_start,
+        finish: offset - 1
+      }
+
+      # 更新进度条
+      if offset % chunk_size == 0 || offset == max_length
+        progress = offset.to_f / max_length * 100
+        filled = ('=' * (progress / 5)).ljust(20)
+        print "Progress: [#{filled}] %.1f%%\r" % progress
+      end
+    end
+
+    print "Progress: [====================] 100.0%\n"
+
+    # 处理长度不一致的情况
+    if content1.bytesize != content2.bytesize
+      shorter = [content1.bytesize, content2.bytesize].min
+      longer = [content1.bytesize, content2.bytesize].max
+      file_label = content1.bytesize > content2.bytesize ? "File1" : "File2"
+      results << { same: nil, start: shorter, finish: longer - 1, file: file_label }
+    end
+
+    print_results(results, content1, content2)
+  end
+
+  def self.print_results(results, content1, content2)
+    total_same_bytes = 0
+    total_diff_bytes = 0
+
+    results.each do |result|
+      if result[:same] == true
+        total_same_bytes += result[:finish] - result[:start] + 1
+      elsif result[:same] == false
+        total_diff_bytes += result[:finish] - result[:start] + 1
+      end
+    end
+
+    len1 = content1.bytesize
+    len2 = content2.bytesize
+    min_len = [len1, len2].min
+    max_len = [len1, len2].max
+
+    percent_matched = (total_same_bytes.to_f / min_len) * 100
+    percent_relative = (total_same_bytes.to_f / max_len) * 100
+
+    puts "Comparing files of size #{len1} and #{len2} bytes:"
+    puts
+
+    results.each do |result|
+      start = format("0x%04X", result[:start])
+      finish = format("0x%04X", result[:finish])
+
+      if result[:same] == true
+        puts "[Identical] Bytes #{start} to #{finish} (#{result[:finish] - result[:start] + 1} bytes)"
+      elsif result[:same] == false
+        puts "[Different] Bytes #{start} to #{finish} (#{result[:finish] - result[:start] + 1} bytes)"
+
+        hex1 = content1.byteslice(result[:start], result[:finish] - result[:start] + 1).bytes.map { |b| format("%02X", b) }
+        hex2 = content2.byteslice(result[:start], result[:finish] - result[:start] + 1).bytes.map { |b| format("%02X", b) }
+
+        display_hex(hex1, "File1")
+        display_hex(hex2, "File2")
+      else
+        file_label = result[:file]
+        puts "[Extra] #{file_label} has #{result[:finish] - result[:start] + 1} extra bytes from #{start} to #{finish}"
+      end
+    end
+
+    puts
+    puts "Different bytes: #{total_diff_bytes} byte(s)"
+    puts "Similarity: %.5f%% (matched / min length) / %.5f%% (matched / max length)" % [
+      percent_matched,
+      percent_relative
+    ]
+  end
+
+  def self.display_hex(bytes_array, label)
+    return if bytes_array.empty?
+
+    if bytes_array.size <= 16
+      line = bytes_array.join(" ")
+      puts "#{label}: #{line}"
+    else
+      head = bytes_array[0..7].join(" ")
+      tail = bytes_array[-8..-1].join(" ")
+      puts "#{label}: #{head} ... #{tail}"
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: rbindiff
+version: !ruby/object:Gem::Version
+  version: 2025.6.21
+platform: ruby
+authors:
+- Hxcan Cai
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Compare two binary files byte-by-byte and show differences in hex.
+email:
+- caihuosheng@email.com
+executables:
+- rbindiff
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/rbindiff
+- lib/rbindiff.rb
+homepage: https://github.com/hxcan/rbindiff
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A binary file comparison tool
+test_files: []