omnizip 0.3.1

data/docs/compatibility.adoc

@@ -0,0 +1,579 @@
+---
+title: Compatibility Matrix
+nav_order: 10
+---
+
+== Purpose
+
+This page provides a comprehensive comparison of Omnizip with other archive utilities to help you make informed decisions about which tool to use for your needs.
+
+== Quick Comparison
+
+[cols="3,1,1,1,1,1,1,1"]
+|===
+|Feature |Omnizip |rubyzip |7-Zip |WinRAR |PeaZip |libarchive |Info-ZIP
+
+|**Language**
+|Pure Ruby
+|Pure Ruby
+|C++
+|C++
+|C++
+|C
+|C
+
+|**Formats Supported**
+|11
+|1 (ZIP)
+|20+
+|30+
+|200+
+|30+
+|1 (ZIP)
+
+|**No Dependencies**
+|✅
+|✅
+|❌
+|❌
+|❌
+|❌
+|❌
+
+|**Cross-Platform**
+|✅
+|✅
+|✅
+|Windows
+|✅
+|✅
+|✅
+
+|**LZMA/LZMA2**
+|✅
+|❌
+|✅
+|✅
+|✅
+|✅
+|❌
+
+|**Advanced Algorithms**
+|8 algorithms
+|1 (Deflate)
+|8+
+|10+
+|Varies
+|Multiple
+|1
+
+|**AES Encryption**
+|✅
+|Partial
+|✅
+|✅
+|✅
+|✅
+|❌
+
+|**Streaming Support**
+|✅
+|✅
+|Partial
+|Partial
+|❌
+|✅
+|Partial
+
+|**Progress Tracking**
+|✅
+|❌
+|✅
+|✅
+|✅
+|❌
+|❌
+
+|**Parallel Processing**
+|✅
+|❌
+|✅
+|✅
+|Partial
+|❌
+|❌
+
+|**Ruby API**
+|✅
+|✅
+|❌
+|❌
+|❌
+|Bindings
+|❌
+
+|**Active Development**
+|✅
+|✅
+|✅
+|✅
+|✅
+|✅
+|⚠️
+|===
+
+== Detailed Comparisons
+
+=== Omnizip vs Rubyzip
+
+[cols="2,1,1,3"]
+|===
+|Feature |Omnizip |rubyzip |Notes
+
+|**Archive Formats**
+|ZIP, 7z, +9 more
+|ZIP only
+|Omnizip supports multiple formats
+
+|**Compression Algorithms**
+|8 algorithms
+|1 (Deflate)
+|LZMA2, PPMd, Zstandard, etc.
+
+|**API Compatibility**
+|100%
+|Native
+|Drop-in replacement possible
+
+|**Encryption**
+|AES-256, WinZip AES
+|Traditional, AES (partial)
+|Stronger encryption options
+
+|**Performance**
+|Similar
+|Baseline
+|Pure Ruby, comparable speed
+
+|**Memory Usage**
+|Configurable
+|Standard
+|Streaming reduces memory
+
+|**Parallel Processing**
+|✅
+|❌
+|2-3x speedup available
+
+|**File Size Limits**
+|Unlimited (ZIP64)
+|ZIP64 supported
+|Both handle large files
+|===
+
+**Migration Path**: Use `require 'omnizip/rubyzip_compat'` for seamless migration.
+
+=== Omnizip vs 7-Zip
+
+[cols="2,1,1,3"]
+|===
+|Feature |Omnizip |7-Zip |Notes
+
+|**Implementation**
+|Pure Ruby
+|Native C++
+|Different performance characteristics
+
+|**Compression Ratio**
+|95%+ of 7-Zip
+|Best-in-class
+|Comparable results
+
+|**Speed**
+|10-60x slower
+|Fastest
+|Trade-off for portability
+
+|**API Access**
+|Ruby API
+|CLI only
+|Programmatic vs command-line
+
+|**Memory Efficiency**
+|Configurable
+|Optimized
+|Streaming available in both
+
+|**Parallel Processing**
+|2-3x speedup
+|3-4x speedup
+|Both support multi-core
+
+|**Format Support**
+|ZIP, 7z, +9
+|20+ formats
+|7-Zip supports more formats
+
+|**Platform Support**
+|All (Ruby)
+|Cross-platform
+|Both widely available
+|===
+
+**When to Choose Omnizip**: Need Ruby API, programmatic control, or rubyzip compatibility
+**When to Choose 7-Zip**: Maximum speed, CLI tools, broader format support
+
+=== Omnizip vs WinRAR
+
+[cols="2,1,1,3"]
+|===
+|Feature |Omnizip |WinRAR |Notes
+
+|**RAR Format**
+|Read-only
+|Read/Write
+|License restrictions on RAR creation
+
+|**Compression**
+|8 algorithms
+|10+ algorithms
+|Both offer advanced compression
+
+|**Licensing**
+|LGPL 2.1 (Free)
+|Proprietary (Paid)
+|Omnizip is free and open source
+
+|**Platform**
+|All platforms
+|Primarily Windows
+|Omnizip more portable
+
+|**API**
+|Full Ruby API
+|Limited
+|Better programmatic access
+
+|**Recovery Records**
+|Limited
+|Excellent
+|WinRAR stronger for recovery
+|===
+
+=== Omnizip vs libarchive
+
+[cols="2,1,1,3"]
+|===
+|Feature |Omnizip |libarchive |Notes
+
+|**Language**
+|Pure Ruby
+|C library
+|Different integration approaches
+
+|**Format Support**
+|11 formats
+|30+ formats
+|libarchive more comprehensive
+
+|**Dependencies**
+|None
+|System library
+|Omnizip easier to deploy
+
+|**Performance**
+|Good
+|Excellent
+|Native C is faster
+
+|**API Quality**
+|Ruby-native
+|C API + bindings
+|Omnizip more Ruby-friendly
+
+|**Streaming**
+|✅ Full
+|✅ Full
+|Both excel at streaming
+|===
+
+== Feature Matrix by Tool
+
+=== Compression Algorithms
+
+[cols="2,1,1,1,1,1"]
+|===
+|Algorithm |Omnizip |rubyzip |7-Zip |WinRAR |libarchive
+
+|Store (no compression)
+|✅
+|✅
+|✅
+|✅
+|✅
+
+|Deflate
+|✅
+|✅
+|✅
+|✅
+|✅
+
+|Deflate64
+|✅
+|❌
+|✅
+|✅
+|❌
+
+|LZMA
+|✅
+|❌
+|✅
+|✅
+|✅
+
+|LZMA2
+|✅
+|❌
+|✅
+|✅
+|✅
+
+|BZip2
+|✅
+|❌
+|✅
+|✅
+|✅
+
+|PPMd7/8
+|✅
+|❌
+|✅
+|✅
+|❌
+
+|Zstandard
+|✅
+|❌
+|✅
+|❌
+|✅
+|===
+
+=== Archive Formats
+
+[cols="2,1,1,1,1,1"]
+|===
+|Format |Omnizip |rubyzip |7-Zip |WinRAR |libarchive
+
+|ZIP
+|✅ Full
+|✅ Full
+|✅ Full
+|✅ Full
+|✅ Full
+
+|ZIP64
+|✅
+|✅
+|✅
+|✅
+|✅
+
+|7z
+|✅ Full
+|❌
+|✅ Full
+|✅ Full
+|Partial
+
+|RAR
+|Read-only
+|❌
+|Read-only
+|✅ Full
+|Read-only
+
+|TAR
+|✅
+|❌
+|✅
+|✅
+|✅ Full
+
+|GZIP
+|✅
+|❌
+|✅
+|✅
+|✅
+
+|BZIP2
+|✅
+|❌
+|✅
+|✅
+|✅
+
+|XZ
+|✅
+|❌
+|✅
+|✅
+|✅
+
+|ISO
+|Read-only
+|❌
+|✅
+|✅
+|✅
+|===
+
+== Use Case Recommendations
+
+=== Choose Omnizip When:
+
+✅ You need a pure Ruby solution (no native extensions)
+✅ You want 7-Zip format support in Ruby
+✅ You're migrating from rubyzip and need better compression
+✅ You need both ZIP and 7z formats in one library
+✅ You want programmatic Ruby API with good documentation
+✅ You need streaming and in-memory operations
+✅ Cross-platform consistency is critical
+
+=== Choose Rubyzip When:
+
+✅ You only need ZIP format support
+✅ You have existing rubyzip code to maintain
+✅ Pure simplicity is more important than features
+✅ ZIP compatibility is your only requirement
+
+=== Choose 7-Zip When:
+
+✅ Maximum compression ratio is required
+✅ You're working with very large files
+✅ Command-line interface is acceptable
+✅ Native C++ performance is essential
+✅ You need the broadest format support
+
+=== Choose WinRAR When:
+
+✅ You specifically need RAR format write support
+✅ You're primarily on Windows platform
+✅ You have a WinRAR license
+✅ Recovery records are critical
+
+== Migration Guides
+
+=== From Rubyzip to Omnizip
+
+Simplest migration - add one line:
+
+[source,ruby]
+----
+# Add this at the top of your file
+require 'omnizip/rubyzip_compat'
+
+# All existing Zip::* code now uses Omnizip
+Zip::File.open('archive.zip') do |zip|
+  # Works exactly the same
+end
+----
+
+See link:guides/migration-rubyzip.html[Complete Migration Guide]
+
+=== From 7-Zip CLI to Omnizip API
+
+Replace command-line calls with Ruby API:
+
+[source,ruby]
+----
+# Instead of: system('7z a archive.7z files/')
+Omnizip::Archive.create('archive.7z', format: :seven_zip) do |archive|
+  archive.add_directory('files/')
+end
+----
+
+== Performance Comparison
+
+[cols="2,1,1,1,1"]
+|===
+|Operation |Omnizip |rubyzip |7-Zip |Relative
+
+|Create 100MB ZIP
+|30s
+|28s
+|3s
+|Similar to rubyzip
+
+|Extract 100MB ZIP
+|18s
+|17s
+|2s
+|Comparable
+
+|Create 100MB 7z
+|45s
+|N/A
+|5s
+|N/A (unique feature)
+
+|LZMA2 compression
+|60s
+|N/A
+|4s
+|Pure Ruby trade-off
+|===
+
+*Environment: MacBook Pro M1, Ruby 3.2, 10KB files*
+
+== Platform Support
+
+[cols="2,1,1,1,1"]
+|===
+|Platform |Omnizip |rubyzip |7-Zip |WinRAR
+
+|Linux
+|✅ Full
+|✅ Full
+|✅ Full
+|⚠️ Limited
+
+|macOS
+|✅ Full
+|✅ Full
+|✅ Full
+|⚠️ Limited
+
+|Windows
+|✅ Full
+|✅ Full
+|✅ Full
+|✅ Native
+
+|BSD
+|✅ Full
+|✅ Full
+|✅ Full
+|❌
+|===
+
+== Summary
+
+Omnizip successfully combines:
+
+* **rubyzip's ease of use** with drop-in API compatibility
+* **7-Zip's powerful compression** with 95%+ algorithm parity
+* **Unique Ruby-native capabilities** not found in other tools
+
+This makes Omnizip ideal for Ruby applications needing advanced compression beyond basic ZIP/Deflate while maintaining compatibility and portability.
+
+== See Also
+
+* link:getting-started/installation.html[Installation Guide]
+* link:guides/migration-rubyzip.html[Migration from Rubyzip]
+* link:getting-started/quick-start.html[Quick Start Tutorial]
+* link:reference/index.html[API Reference]

data/docs/concepts/index.adoc

@@ -0,0 +1,129 @@
+---
+title: Core Concepts
+nav_order: 40
+---
+
+== Core Concepts
+
+Understanding the fundamental concepts behind Omnizip's architecture.
+
+=== Registry-Based Architecture
+
+Omnizip uses a registry pattern for extensibility:
+
+==== Algorithm Registry
+
+Manages compression algorithms:
+
+[source,ruby]
+----
+# List algorithms
+Omnizip::AlgorithmRegistry.registered
+
+# Get algorithm
+algorithm = Omnizip::AlgorithmRegistry.get(:lzma2).new(level: 9)
+
+# Register custom algorithm
+Omnizip::AlgorithmRegistry.register(:custom, CustomAlgorithm)
+----
+
+==== Filter Registry
+
+Manages preprocessing filters:
+
+[source,ruby]
+----
+# List filters
+Omnizip::FilterRegistry.registered
+
+# Get filter
+filter = Omnizip::FilterRegistry.get(:bcj_x86).new
+----
+
+==== Format Registry
+
+Manages archive formats:
+
+[source,ruby]
+----
+# List formats
+Omnizip::FormatRegistry.registered
+
+# Get format
+format = Omnizip::FormatRegistry.get(:seven_zip)
+----
+
+=== Compression Pipeline
+
+Omnizip's compression process:
+
+. **Input** - Raw data stream
+. **Filter Chain** - Optional preprocessing (BCJ, Delta)
+. **Compression** - Algorithm compression (LZMA2, etc.)
+. **Archive Container** - Format packaging (7z, ZIP)
+. **Output** - Compressed archive
+
+=== Solid Compression
+
+Solid archives use a shared dictionary across multiple files:
+
+* **Advantage**: 10-30% better compression for similar files
+* **Disadvantage**: Cannot extract individual files independently
+* **Best for**: Source code, text documents, log files
+
+=== Multi-Volume Archives
+
+Split large archives across multiple files:
+
+* **Naming**: archive.7z.001, archive.7z.002, etc.
+* **Use case**: Large files, optical media, file size limits
+* **Extraction**: Automatic from any volume
+
+=== Encryption
+
+Omnizip supports AES-256 encryption:
+
+* **7z**: Header + file encryption
+* **RAR5**: File-only encryption
+* **Algorithm**: AES-256-CBC with PBKDF2 key derivation
+
+=== Checksums
+
+Integrity verification:
+
+* **CRC32**: Fast, common checksum
+* **CRC64**: More reliable for large files
+* **SHA256**: Cryptographic verification
+* **BLAKE2sp**: Fast, secure checksum
+
+=== Compression Algorithms
+
+==== Dictionary-Based (LZMA/LZMA2)
+
+* Sliding window dictionary
+* Range encoding for probabilities
+* High compression ratios
+
+==== Statistical (BZip2)
+
+* Burrows-Wheeler Transform
+* Move-to-Front coding
+* Huffman encoding
+
+==== Context Modeling (PPMd)
+
+* Prediction by Partial Matching
+* Context-based probability models
+* Excellent for text
+
+==== Dictionary + Huffman (Deflate)
+
+* LZ77 sliding window
+* Huffman coding
+* ZIP-compatible
+
+=== See Also
+
+* link:../developer/architecture[Architecture Details]
+* link:../guides/compression-algorithms/[Algorithm Guides]
+* link:../guides/archive-formats/[Format Guides]