omnizip 0.3.1

data/examples/api_comparison.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# API Comparison Demo
+# Shows both Rubyzip compatibility and native Omnizip APIs side-by-side
+#
+
+puts "=== Omnizip: Dual API Demonstration ==="
+puts "Showing both rubyzip-compatible and native APIs"
+puts
+
+require "tmpdir"
+tmpdir = Dir.mktmpdir("omnizip_comparison")
+
+# =============================================================================
+# Example 1: Creating an archive
+# =============================================================================
+puts "1. Creating a ZIP archive"
+puts "   #{'=' * 70}"
+
+zip1_path = File.join(tmpdir, "compat.zip")
+zip2_path = File.join(tmpdir, "native.zip")
+
+# Rubyzip-compatible approach
+puts "\n   A) Rubyzip-compatible API:"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  require 'omnizip/rubyzip_compat'
+
+  Zip::File.open('archive.zip', create: true) do |zip|
+    zip.add('file.txt') { 'Content' }
+  end
+CODE
+
+require "omnizip/rubyzip_compat"
+Zip::File.open(zip1_path, create: true) do |zip|
+  zip.add("file.txt") { "Content from rubyzip API" }
+end
+puts "   ✓ Created: #{zip1_path}"
+
+# Native Omnizip approach
+puts "\n   B) Native Omnizip API:"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  require 'omnizip'
+
+  Omnizip::Zip::File.create('archive.zip') do |zip|
+    zip.add('file.txt') { 'Content' }
+  end
+CODE
+
+require "omnizip"
+Omnizip::Zip::File.create(zip2_path) do |zip|
+  zip.add("file.txt") { "Content from native API" }
+end
+puts "   ✓ Created: #{zip2_path}"
+
+# =============================================================================
+# Example 2: Reading an archive
+# =============================================================================
+puts "\n\n2. Reading archive contents"
+puts "   #{'=' * 70}"
+
+# Rubyzip-compatible approach
+puts "\n   A) Rubyzip-compatible API:"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  Zip::File.open('archive.zip') do |zip|
+    content = zip.read('file.txt')
+    puts content
+  end
+CODE
+
+content1 = Zip::File.open(zip1_path) { |zip| zip.read("file.txt") }
+puts "   ✓ Read: #{content1}"
+
+# Native Omnizip approach
+puts "\n   B) Native Omnizip API (convenience method):"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  content = Omnizip.read_from_archive('archive.zip', 'file.txt')
+  puts content
+CODE
+
+content2 = Omnizip.read_from_archive(zip2_path, "file.txt")
+puts "   ✓ Read: #{content2}"
+
+# =============================================================================
+# Example 3: Working with directories
+# =============================================================================
+puts "\n\n3. Compressing a directory"
+puts "   #{'=' * 70}"
+
+# Create sample directory
+sample_dir = File.join(tmpdir, "sample")
+FileUtils.mkdir_p(File.join(sample_dir, "subdir"))
+File.write(File.join(sample_dir, "file1.txt"), "File 1")
+File.write(File.join(sample_dir, "file2.txt"), "File 2")
+File.write(File.join(sample_dir, "subdir", "file3.txt"), "File 3")
+
+zip3_path = File.join(tmpdir, "dir_compat.zip")
+zip4_path = File.join(tmpdir, "dir_native.zip")
+
+# Rubyzip-compatible approach
+puts "\n   A) Rubyzip-compatible API (manual iteration):"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  Zip::File.open('backup.zip', create: true) do |zip|
+    Dir.glob('dir/**/*').each do |file|
+      next if File.directory?(file)
+      zip.add(file.sub('dir/', ''), file)
+    end
+  end
+CODE
+
+Zip::File.open(zip3_path, create: true) do |zip|
+  Dir.glob(File.join(sample_dir, "**/*")).each do |file|
+    rel_path = file.sub("#{sample_dir}/", "")
+    if File.directory?(file)
+      zip.add("#{rel_path}/")
+    else
+      zip.add(rel_path, file)
+    end
+  end
+end
+puts "   ✓ Created with #{Zip::File.open(zip3_path) do |z|
+  z.entries.size
+end} entries"
+
+# Native Omnizip approach
+puts "\n   B) Native Omnizip API (one-liner):"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  Omnizip.compress_directory('dir/', 'backup.zip')
+CODE
+
+Omnizip.compress_directory(sample_dir, zip4_path)
+puts "   ✓ Created with #{Omnizip.list_archive(zip4_path).size} entries"
+
+# =============================================================================
+# Example 4: Both APIs work on same archive
+# =============================================================================
+puts "\n\n4. Both APIs can work on the same archive"
+puts "   #{'=' * 70}"
+
+shared_zip = File.join(tmpdir, "shared.zip")
+
+# Create with rubyzip API
+puts "\n   Creating with Rubyzip API..."
+Zip::File.create(shared_zip) do |zip|
+  zip.add("from_rubyzip.txt") { "Created with Zip::" }
+end
+
+# Modify with native API
+puts "   Modifying with Native API..."
+source = File.join(tmpdir, "from_native.txt")
+File.write(source, "Added with Omnizip")
+Omnizip.add_to_archive(shared_zip, "from_native.txt", source)
+
+# Read with both APIs
+puts "\n   Reading with both APIs:"
+Zip::File.open(shared_zip) do |zip|
+  puts "   - Rubyzip sees: #{zip.names.join(', ')}"
+end
+puts "   - Native sees: #{Omnizip.list_archive(shared_zip).join(', ')}"
+
+# =============================================================================
+# Summary
+# =============================================================================
+puts "\n\n#{'=' * 76}"
+puts "SUMMARY: Which API should you use?"
+puts "=" * 76
+puts <<~SUMMARY
+
+  ┌─ Rubyzip Compatibility API ────────────────────────────────────────┐
+  │                                                                     │
+  │  Use when:                                                          │
+  │  • Migrating from rubyzip                                           │
+  │  • Maintaining existing code                                        │
+  │  • Need drop-in compatibility                                       │
+  │                                                                     │
+  │  require 'omnizip/rubyzip_compat'                                   │
+  │  Zip::File.open('archive.zip') { ... }                              │
+  │                                                                     │
+  └─────────────────────────────────────────────────────────────────────┘
+
+  ┌─ Native Omnizip API ───────────────────────────────────────────────┐
+  │                                                                     │
+  │  Use when:                                                          │
+  │  • Starting new projects                                            │
+  │  • Want convenience methods                                         │
+  │  • Need cleaner, more Ruby-idiomatic code                           │
+  │                                                                     │
+  │  require 'omnizip'                                                  │
+  │  Omnizip.compress_file('file.txt', 'archive.zip')                   │
+  │                                                                     │
+  └─────────────────────────────────────────────────────────────────────┘
+
+  💡 Both APIs work seamlessly together - choose based on your needs!
+
+SUMMARY
+
+puts "All demo files created in: #{tmpdir}"
+puts

data/examples/deflate64_example.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "omnizip"
+
+# Example: Using Deflate64 compression algorithm
+#
+# Deflate64 (Enhanced Deflate) extends standard Deflate with:
+# - 64KB sliding window (vs 32KB)
+# - Better compression for large files
+# - ZIP compression method 9
+
+puts "=" * 60
+puts "Deflate64 Algorithm Example"
+puts "=" * 60
+puts
+
+# Example 1: Basic Deflate64 compression
+puts "1. Basic Deflate64 compression"
+puts "-" * 60
+
+original_data = "Hello, World! " * 1000
+puts "Original size: #{original_data.bytesize} bytes"
+
+# Compress using Deflate64
+compressed = StringIO.new
+algorithm = Omnizip::Algorithms::Deflate64.new
+algorithm.compress(StringIO.new(original_data), compressed)
+
+puts "Compressed size: #{compressed.string.bytesize} bytes"
+puts "Compression ratio: #{(compressed.string.bytesize.to_f / original_data.bytesize * 100).round(2)}%"
+
+# Decompress
+decompressed = StringIO.new
+algorithm.decompress(StringIO.new(compressed.string), decompressed)
+
+puts "Decompressed size: #{decompressed.string.bytesize} bytes"
+puts "Data integrity: #{decompressed.string == original_data ? '✓ OK' : '✗ FAILED'}"
+puts
+
+# Example 2: Deflate64 with large data (benefits from 64KB window)
+puts "2. Deflate64 with large repetitive data"
+puts "-" * 60
+
+large_data = ("Pattern#{rand(1000)} " * 100) * 500
+puts "Original size: #{large_data.bytesize} bytes"
+
+compressed_large = StringIO.new
+algorithm.compress(StringIO.new(large_data), compressed_large)
+
+puts "Compressed size: #{compressed_large.string.bytesize} bytes"
+puts "Compression ratio: #{(compressed_large.string.bytesize.to_f / large_data.bytesize * 100).round(2)}%"
+puts
+
+# Example 3: Creating a ZIP archive with Deflate64
+puts "3. Creating ZIP archive with Deflate64"
+puts "-" * 60
+
+# Note: This requires ZIP format integration
+# Once integrated, usage would be:
+#
+# Omnizip::Archive.create("test.zip") do |archive|
+#   archive.compression_method = :deflate64
+#   archive.add_file("example.txt", "Large file content...")
+# end
+
+puts "ZIP integration: Coming in v2.0"
+puts "Deflate64 will be available as compression method 9"
+puts
+
+# Example 4: Algorithm metadata
+puts "4. Deflate64 algorithm metadata"
+puts "-" * 60
+
+metadata = Omnizip::Algorithms::Deflate64.metadata
+puts "Name: #{metadata[:name]}"
+puts "Type: #{metadata[:type]}"
+puts "Dictionary size: #{metadata[:dictionary_size]} bytes (#{metadata[:dictionary_size] / 1024}KB)"
+puts "ZIP method ID: #{metadata[:compression_method]}"
+puts "Streaming: #{metadata[:streaming_supported] ? 'Yes' : 'No'}"
+puts
+
+# Example 5: Comparison with standard Deflate
+puts "5. Deflate64 advantages"
+puts "-" * 60
+puts "✓ 64KB dictionary (2x larger than standard Deflate)"
+puts "✓ Better compression for files > 32KB"
+puts "✓ Fully compatible with 7-Zip and PKZip"
+puts "✓ Streaming support for large files"
+puts "✓ Same Huffman coding as standard Deflate"
+puts
+
+puts "=" * 60
+puts "Example complete!"
+puts "=" * 60

data/examples/par2_demo.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# PAR2 Parity Archive Demo
+# Demonstrates creating, verifying, and repairing files with PAR2 error correction
+
+require "bundler/setup"
+require "omnizip/parity"
+require "tempfile"
+require "fileutils"
+
+def demo_par2_workflow
+  puts "=== PAR2 Parity Archive Demo ==="
+  puts
+
+  # Create temporary directory for demo
+  temp_dir = Dir.mktmpdir("par2_demo")
+
+  begin
+    # Step 1: Create test files
+    puts "Step 1: Creating test files..."
+    file1 = File.join(temp_dir, "important_data.txt")
+    file2 = File.join(temp_dir, "documents.txt")
+
+    File.write(file1, "This is important data! " * 100)
+    File.write(file2, "These are valuable documents. " * 100)
+    puts "  ✓ Created test files (#{File.size(file1) + File.size(file2)} bytes total)"
+    puts
+
+    # Step 2: Create PAR2 protection
+    puts "Step 2: Creating PAR2 recovery files with 10% redundancy..."
+    creator = Omnizip::Parity::Par2Creator.new(
+      redundancy: 10,
+      block_size: 1024,
+      progress: ->(pct, msg) { puts "  [#{pct}%] #{msg}" },
+    )
+
+    creator.add_file(file1)
+    creator.add_file(file2)
+
+    par2_files = creator.create(File.join(temp_dir, "backup"))
+    puts "  ✓ Created #{par2_files.size} PAR2 files"
+    par2_files.each { |f| puts "    - #{File.basename(f)}" }
+    puts
+
+    # Step 3: Verify intact files
+    puts "Step 3: Verifying file integrity..."
+    verifier = Omnizip::Parity::Par2Verifier.new(par2_files.first)
+    result = verifier.verify
+
+    if result.all_ok?
+      puts "  ✓ All files intact!"
+      puts "    Total blocks: #{result.total_blocks}"
+      puts "    Recovery blocks: #{result.recovery_blocks}"
+    else
+      puts "  ✗ Verification failed (unexpected!)"
+    end
+    puts
+
+    # Step 4: Simulate corruption
+    puts "Step 4: Simulating file corruption..."
+    corrupted_content = "CORRUPTED DATA! " * 100
+    File.write(file1, corrupted_content)
+    puts "  ✓ Corrupted #{File.basename(file1)}"
+    puts
+
+    # Step 5: Verify corrupted file
+    puts "Step 5: Verifying corrupted files..."
+    result2 = verifier.verify
+
+    if result2.all_ok?
+      puts "  ✗ No corruption detected (unexpected!)"
+    else
+      puts "  ✓ Detected corruption:"
+      puts "    Damaged files: #{result2.damaged_files.join(', ')}"
+      puts "    Damaged blocks: #{result2.damaged_blocks.size}"
+      puts "    Repairable: #{result2.repairable?}"
+    end
+    puts
+
+    # Step 6: Repair damaged file
+    if result2.repairable?
+      puts "Step 6: Repairing corrupted files..."
+      repairer = Omnizip::Parity::Par2Repairer.new(
+        par2_files.first,
+        progress: ->(pct, msg) { puts "  [#{pct}%] #{msg}" },
+      )
+
+      repair_result = repairer.repair
+
+      if repair_result.success?
+        puts "  ✓ Repair successful!"
+        puts "    Recovered files: #{repair_result.recovered_files.join(', ')}"
+        puts "    Recovered blocks: #{repair_result.recovered_blocks}"
+
+        # Verify repair worked
+        result3 = verifier.verify
+        if result3.all_ok?
+          puts "  ✓ Verification after repair: All files intact!"
+        else
+          puts "  ✗ Verification after repair failed"
+        end
+      else
+        puts "  ✗ Repair failed: #{repair_result.error_message}"
+      end
+    else
+      puts "Step 6: Cannot repair - insufficient recovery blocks"
+    end
+  ensure
+    # Cleanup
+    puts
+    puts "Cleaning up temporary files..."
+    FileUtils.rm_rf(temp_dir)
+    puts "Demo complete!"
+  end
+end
+
+# Run the demo
+if __FILE__ == $PROGRAM_NAME
+  demo_par2_workflow
+end

data/examples/quick_start_native.rb

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# Native Omnizip API Demo
+# Shows how to use Omnizip's native convenience methods
+#
+
+require "omnizip"
+
+puts "=== Native Omnizip API Demo ==="
+puts "Using Omnizip's native convenience methods"
+puts
+
+# Create a temporary directory for examples
+require "tmpdir"
+tmpdir = Dir.mktmpdir("omnizip_native_demo")
+
+begin
+  # Example 1: Compress a single file
+  puts "1. Compressing a single file..."
+  source_file = File.join(tmpdir, "document.txt")
+  File.write(source_file, "This is a sample document with some content.")
+
+  zip_file = File.join(tmpdir, "document.zip")
+  Omnizip.compress_file(source_file, zip_file)
+
+  puts "   Compressed: #{source_file} -> #{zip_file}"
+  puts "   Original size: #{File.size(source_file)} bytes"
+  puts "   Compressed size: #{File.size(zip_file)} bytes"
+  puts
+
+  # Example 2: Compress a directory
+  puts "2. Compressing a directory..."
+  source_dir = File.join(tmpdir, "project")
+  FileUtils.mkdir_p(File.join(source_dir, "src"))
+  FileUtils.mkdir_p(File.join(source_dir, "docs"))
+  File.write(File.join(source_dir, "README.md"), "# Project README")
+  File.write(File.join(source_dir, "src", "main.rb"), "puts 'Hello, World!'")
+  File.write(File.join(source_dir, "docs", "guide.txt"), "User Guide")
+
+  backup_zip = File.join(tmpdir, "project_backup.zip")
+  Omnizip.compress_directory(source_dir, backup_zip)
+
+  puts "   Compressed directory: #{source_dir}"
+  puts "   Archive created: #{backup_zip}"
+  puts
+
+  # Example 3: List archive contents
+  puts "3. Listing archive contents..."
+  names = Omnizip.list_archive(backup_zip)
+  puts "   Archive contains #{names.size} entries:"
+  names.each { |name| puts "     - #{name}" }
+  puts
+
+  # Example 4: List with details
+  puts "4. Listing with detailed information..."
+  details = Omnizip.list_archive(backup_zip, details: true)
+  details.each do |entry|
+    type = entry[:directory] ? "[DIR]" : "[FILE]"
+    ratio = entry[:size].positive? ? (100 * entry[:compressed_size].to_f / entry[:size]).round(1) : 0
+    puts "   #{type} #{entry[:name]}"
+    puts "       Size: #{entry[:size]} bytes, Compressed: #{entry[:compressed_size]} bytes (#{ratio}%)"
+  end
+  puts
+
+  # Example 5: Read a file from archive
+  puts "5. Reading file from archive..."
+  content = Omnizip.read_from_archive(backup_zip, "README.md")
+  puts "   README.md content:"
+  puts "   #{content}"
+  puts
+
+  # Example 6: Extract archive
+  puts "6. Extracting archive..."
+  extract_dir = File.join(tmpdir, "extracted")
+  extracted_files = Omnizip.extract_archive(backup_zip, extract_dir)
+
+  puts "   Extracted #{extracted_files.size} entries to: #{extract_dir}"
+  extracted_files.each { |f| puts "     - #{f}" }
+  puts
+
+  # Example 7: Add file to existing archive
+  puts "7. Adding file to existing archive..."
+  new_file = File.join(tmpdir, "changelog.txt")
+  File.write(new_file, "v1.0.0 - Initial release")
+
+  Omnizip.add_to_archive(backup_zip, "CHANGELOG.txt", new_file)
+
+  updated_names = Omnizip.list_archive(backup_zip)
+  puts "   Added CHANGELOG.txt to archive"
+  puts "   Archive now has #{updated_names.size} entries"
+  puts
+
+  # Example 8: Remove file from archive
+  puts "8. Removing file from archive..."
+  Omnizip.remove_from_archive(backup_zip, "docs/guide.txt")
+
+  final_names = Omnizip.list_archive(backup_zip)
+  puts "   Removed docs/guide.txt"
+  puts "   Archive now has #{final_names.size} entries"
+  puts
+
+  # Example 9: Using low-level API for advanced features
+  puts "9. Using low-level API for advanced control..."
+  advanced_zip = File.join(tmpdir, "advanced.zip")
+
+  Omnizip::Zip::File.create(advanced_zip) do |zip|
+    zip.add("data.txt") { "Some data" }
+    zip.add("more_data.txt") { "More data" }
+
+    # Set archive comment
+    zip.comment = "Created with Omnizip native API"
+  end
+
+  Omnizip::Zip::File.open(advanced_zip) do |zip|
+    puts "   Archive comment: #{zip.comment}"
+    puts "   Contains #{zip.size} entries"
+  end
+  puts
+
+  # Example 10: Streaming API
+  puts "10. Using streaming API..."
+  stream_zip = File.join(tmpdir, "streamed.zip")
+
+  Omnizip::Zip::OutputStream.open(stream_zip) do |zos|
+    zos.put_next_entry("log.txt")
+    zos.puts("Log entry 1")
+    zos.puts("Log entry 2")
+    zos.puts("Log entry 3")
+
+    zos.put_next_entry("data.bin")
+    zos.write([1, 2, 3, 4, 5].pack("C*"))
+  end
+
+  puts "   Created streaming archive: #{stream_zip}"
+  puts
+
+  puts "=== Demo Complete ==="
+  puts "All files created in: #{tmpdir}"
+  puts
+  puts "Key advantages of native API:"
+  puts "  - Simple convenience methods for common operations"
+  puts "  - Automatic resource management"
+  puts "  - Clear, readable code"
+  puts "  - Full control when needed via low-level API"
+
+  # Cleanup (optional - tmpdir usually handles this)
+  # FileUtils.rm_rf(tmpdir)
+end

data/examples/quick_start_rubyzip.rb

@@ -0,0 +1,115 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# Rubyzip Compatibility Demo
+# Shows how to use Omnizip as a drop-in replacement for rubyzip
+#
+
+require "omnizip/rubyzip_compat"
+
+puts "=== Rubyzip Compatibility Demo ==="
+puts "Using Omnizip with rubyzip-compatible API"
+puts
+
+# Create a temporary directory for examples
+require "tmpdir"
+tmpdir = Dir.mktmpdir("omnizip_rubyzip_demo")
+
+begin
+  # Example 1: Create a ZIP archive using Zip::File
+  puts "1. Creating ZIP archive with Zip::File..."
+  zip_path = File.join(tmpdir, "example.zip")
+
+  Zip::File.open(zip_path, create: true) do |zipfile|
+    # Add files from block
+    zipfile.add("readme.txt") { "This is a README file" }
+    zipfile.add("config.yml") { "version: 1.0\nname: example" }
+
+    # Add directory
+    zipfile.add("data/")
+    zipfile.add("data/values.txt") { "value1\nvalue2\nvalue3" }
+  end
+
+  puts "   Created: #{zip_path}"
+  puts
+
+  # Example 2: Read archive contents
+  puts "2. Reading archive contents..."
+  Zip::File.open(zip_path) do |zipfile|
+    puts "   Archive contains #{zipfile.entries.size} entries:"
+    zipfile.each do |entry|
+      type = entry.directory? ? "[DIR]" : "[FILE]"
+      puts "     #{type} #{entry.name} (#{entry.size} bytes)"
+    end
+  end
+  puts
+
+  # Example 3: Extract specific file
+  puts "3. Extracting specific file..."
+  Zip::File.open(zip_path) do |zipfile|
+    content = zipfile.read("readme.txt")
+    puts "   readme.txt content: #{content}"
+  end
+  puts
+
+  # Example 4: Use streaming API with Zip::OutputStream
+  puts "4. Creating archive with streaming API..."
+  stream_zip = File.join(tmpdir, "stream.zip")
+
+  Zip::OutputStream.open(stream_zip) do |zos|
+    zos.put_next_entry("stream1.txt")
+    zos.write("First streamed entry")
+
+    zos.put_next_entry("stream2.txt")
+    zos << "Second"
+    zos << " entry"
+  end
+
+  puts "   Created: #{stream_zip}"
+  puts
+
+  # Example 5: Extract all files
+  puts "5. Extracting all files..."
+  output_dir = File.join(tmpdir, "extracted")
+
+  Zip::File.open(zip_path) do |zipfile|
+    zipfile.each do |entry|
+      next if entry.directory?
+
+      dest_path = File.join(output_dir, entry.name)
+      FileUtils.mkdir_p(File.dirname(dest_path))
+      zipfile.extract(entry, dest_path) { true } # Overwrite if exists
+    end
+  end
+
+  puts "   Extracted to: #{output_dir}"
+  extracted_files = Dir.glob(File.join(output_dir, "**/*")).select do |f|
+    File.file?(f)
+  end
+  puts "   Extracted #{extracted_files.size} files"
+  puts
+
+  # Example 6: Modify existing archive
+  puts "6. Modifying existing archive..."
+  Zip::File.open(zip_path) do |zipfile|
+    # Add new file
+    zipfile.add("new_file.txt") { "Added later" }
+
+    # Remove a file
+    zipfile.remove("config.yml")
+  end
+
+  Zip::File.open(zip_path) do |zipfile|
+    puts "   Archive now contains:"
+    zipfile.each { |e| puts "     - #{e.name}" }
+  end
+  puts
+
+  puts "=== Demo Complete ==="
+  puts "All files created in: #{tmpdir}"
+  puts "Note: Temporary directory will be cleaned up automatically"
+
+  # Cleanup (optional - tmpdir usually handles this)
+  # FileUtils.rm_rf(tmpdir)
+end