omnizip 0.3.1

data/docs/guides/archive-formats/xz-format.adoc

@@ -0,0 +1,118 @@
+---
+title: XZ Format
+nav_order: 6
+parent: Archive Formats
+grand_parent: Guides
+---
+
+== Purpose
+
+XZ is a modern compression format based on LZMA2 that provides excellent compression ratios. It's commonly used for Linux package distribution and software archives.
+
+== Key Characteristics
+
+[cols="1,3"]
+|===
+|Property |Value
+
+|Compression
+|LZMA2 (with LZMA, BCJ filters)
+
+|Encryption
+|None
+
+|Archive Support
+|Single file only (use with TAR for multiple files)
+
+|Large Files
+|Yes (up to 4 EB)
+
+|Best For
+|Software packages, maximum compression, Unix systems
+|===
+
+== Basic Usage
+
+=== Compress a File
+
+[source,ruby]
+----
+# Compress single file with XZ
+Omnizip.compress_file('data.bin', 'data.bin.xz',
+  level: 6  # Default level
+)
+
+# Maximum compression
+Omnizip.compress_file('data.bin', 'data.bin.xz',
+  level: 9,
+  extreme: true  # Use more CPU for slightly better ratio
+)
+----
+
+=== Decompress a File
+
+[source,ruby]
+----
+# Decompress XZ file
+Omnizip.decompress_file('data.bin.xz', 'data.bin')
+----
+
+== XZ Utils Compatibility
+
+Omnizip is compatible with files created by XZ Utils:
+
+[source,bash]
+----
+# Create with XZ Utils
+$ xz -k data.bin
+
+# Extract with Omnizip
+Omnizip.decompress_file('data.bin.xz', 'data.bin')
+
+# Create with Omnizip
+Omnizip.compress_file('data.bin', 'data.bin.xz')
+
+# Extract with XZ Utils
+$ xz -d data.bin.xz
+----
+
+== Compression Levels
+
+[cols="1,2,2,2"]
+|===
+|Level |Memory (Compress) |Memory (Decompress) |Typical Use
+
+|1-3
+|4-24 MB
+|1-3 MB
+|Fast compression
+
+|4-6
+|32-96 MB
+|4-9 MB
+|**Default** - balanced
+
+|7-9
+|192-674 MB
+|16-64 MB
+|Maximum compression
+|===
+
+== TAR.XZ Archives
+
+XZ is commonly combined with TAR:
+
+[source,ruby]
+----
+# Create TAR.XZ archive
+Omnizip.compress_directory('project/', 'project.tar.xz',
+  format: :tar_xz,
+  level: 6
+)
+----
+
+== See Also
+
+* link:../compression-algorithms/lzma2.html[LZMA2 Algorithm] - Compression details
+* link:tar-format.html[TAR Format] - Multi-file archives with XZ
+* link:gzip-format.html[GZIP Format] - Faster alternative

data/docs/guides/archive-formats/zip-format.adoc

@@ -0,0 +1,35 @@
+---
+title: ZIP Format
+nav_order: 2
+parent: Archive Formats
+grand_parent: Guides
+---
+
+== ZIP Format
+
+=== General
+
+The ZIP format is a widely used archive format.
+
+=== Features
+
+* Cross-platform compatibility
+* ZIP64 support for large files
+* Deflate compression
+* WinZip AES encryption
+
+=== Usage
+
+[source,bash]
+----
+# Create ZIP archive
+omnizip archive create backup.zip documents/ --format zip
+
+# Extract ZIP archive
+omnizip archive extract backup.zip output/
+----
+
+=== See Also
+
+* link:../compression-algorithms/deflate.html[Deflate Algorithm]
+

data/docs/guides/compression-algorithms/bzip2.adoc

@@ -0,0 +1,113 @@
+---
+title: BZip2
+nav_order: 4
+parent: Compression Algorithms
+grand_parent: Guides
+---
+
+== Purpose
+
+BZip2 is a compression algorithm based on the Burrows-Wheeler Transform (BWT) that provides excellent compression ratios for text files and source code. It's particularly effective for files with repetitive patterns.
+
+== Key Characteristics
+
+[cols="1,3"]
+|===
+|Property |Value
+
+|Compression Ratio
+|Very Good (better than Deflate)
+
+|Compression Speed
+|Medium
+
+|Decompression Speed
+|Medium
+
+|Memory Usage
+|Medium (dependent on block size)
+
+|Best For
+|Text files, source code, structured data
+|===
+
+== When to Use BZip2
+
+**Choose BZip2 when**:
+
+* Compressing text files or source code
+* Need better compression than Deflate
+* Working with structured data (XML, JSON, CSV)
+* Compatibility with Unix/Linux systems is needed
+
+**Consider alternatives when**:
+
+* Speed is critical (use Zstandard)
+* Maximum compression needed (use LZMA2)
+* Binary data (use LZMA2)
+
+== Basic Usage
+
+=== Compress with BZip2
+
+[source,ruby]
+----
+# Create BZip2-compressed file
+Omnizip.compress_file('data.txt', 'data.txt.bz2',
+  algorithm: :bzip2,
+  level: 9
+)
+
+# Create archive with BZip2 compression
+Omnizip::Archive.create('backup.tar.bz2', format: :tar_bzip2) do |archive|
+  archive.add_directory('project/')
+end
+----
+
+=== Decompress BZip2
+
+[source,ruby]
+----
+# Decompress BZip2 file
+Omnizip.decompress_file('data.txt.bz2', 'data.txt')
+
+# Extract BZip2 archive
+Omnizip.extract_archive('backup.tar.bz2', 'output/')
+----
+
+== Compression Levels
+
+BZip2 supports levels 1-9:
+
+[cols="1,2,2,2"]
+|===
+|Level |Speed |Ratio |Best For
+
+|1
+|Fast
+|Good
+|Quick compression
+
+|5
+|Medium
+|Very Good
+|**Default** - balanced
+
+|9
+|Slow
+|Best
+|Maximum compression
+|===
+
+== Technical Details
+
+* **Algorithm**: Burrows-Wheeler Transform + Move-to-Front + Huffman coding
+* **Block Size**: 100KB to 900KB (level dependent)
+* **File Extension**: `.bz2`
+* **Container**: Can be used within TAR archives (`.tar.bz2` or `.tbz2`)
+
+== See Also
+
+* link:lzma.html[LZMA] - Better compression for general data
+* link:deflate.html[Deflate] - Faster alternative
+* link:../../compatibility.html[Compatibility] - BZip2 support across tools

data/docs/guides/compression-algorithms/deflate.adoc

@@ -0,0 +1,319 @@
+---
+title: Deflate
+nav_order: 5
+parent: Compression Algorithms
+grand_parent: Guides
+---
+
+== Purpose
+
+Deflate is the standard ZIP compression algorithm, offering a good balance between compression ratio and speed. It's universally supported and provides fast compression and decompression.
+
+== Key Characteristics
+
+[cols="1,3"]
+|===
+|Property |Value
+
+|Compression Ratio
+|Good
+
+|Compression Speed
+|Fast
+
+|Decompression Speed
+|Very fast
+
+|Memory Usage
+|Low
+
+|Compatibility
+|Universal (ZIP standard)
+
+|Best For
+|General use, speed-critical applications, maximum compatibility
+|===
+
+== When to Use Deflate
+
+**Choose Deflate when**:
+
+* Speed is more important than maximum compression
+* Creating ZIP archives for broad compatibility
+* Working with already-compressed data
+* Need fast decompression
+* Memory is limited
+
+**Consider alternatives when**:
+
+* Maximum compression is priority (use LZMA2)
+* Working with text files (use PPMd)
+* Need even faster compression (use Zstandard)
+
+== Basic Usage
+
+=== Create ZIP with Deflate
+
+[source,ruby]
+----
+# Deflate is the default for ZIP
+Omnizip.compress_directory('project/', 'backup.zip')
+
+# Explicit Deflate configuration
+Omnizip::Archive.create('archive.zip', format: :zip) do |archive|
+  archive.compression = :deflate
+  archive.level = 6  # Default level
+  archive.add_directory('files/')
+end
+----
+
+=== Rubyzip-Compatible API
+
+[source,ruby]
+----
+require 'omnizip/rubyzip_compat'
+
+# Standard ZIP creation with Deflate
+Zip::File.open('archive.zip', create: true) do |zip|
+  zip.add('readme.txt', 'README.md')
+  zip.add('data.json', 'config/data.json')
+end
+----
+
+== Compression Levels
+
+Deflate supports levels 1-9:
+
+[cols="1,2,2,2"]
+|===
+|Level |Speed |Ratio |Best For
+
+|1
+|Fastest
+|Basic
+|Quick archiving, temporary files
+
+|3
+|Very Fast
+|Moderate
+|Development, testing
+
+|6
+|Fast
+|Good
+|**Default** - balanced performance
+
+|9
+|Slower
+|Best
+|Distribution, long-term storage
+|===
+
+.Level Comparison Example
+[source,ruby]
+----
+[1, 6, 9].each do |level|
+  time = Benchmark.measure do
+    Omnizip.compress_file('data.txt', "output-#{level}.zip",
+      compression: :deflate,
+      level: level
+    )
+  end
+
+  size = File.size("output-#{level}.zip")
+  puts "Level #{level}: #{size} bytes in #{time.real.round(2)}s"
+end
+
+# Output:
+# Level 1: 125 KB in 0.05s (fastest)
+# Level 6: 98 KB in 0.12s (balanced)
+# Level 9: 95 KB in 0.28s (best compression)
+----
+
+== Performance Characteristics
+
+=== Speed Comparison
+
+[cols="2,1,1,1"]
+|===
+|File Size |Compress Time |Decompress Time |Throughput
+
+|1 MB
+|0.1s
+|0.05s
+|~10 MB/s
+
+|10 MB
+|1s
+|0.5s
+|~10 MB/s
+
+|100 MB
+|10s
+|5s
+|~10 MB/s
+
+|1 GB
+|100s
+|50s
+|~10 MB/s
+|===
+
+*Note: Times for level 6 on modern hardware*
+
+=== vs Other Algorithms
+
+[cols="2,1,1,1,1"]
+|===
+|Algorithm |Compress |Decompress |Ratio |When to Choose
+
+|**Deflate**
+|Fast
+|Very Fast
+|Good
+|Speed + compatibility
+
+|LZMA2
+|Slow
+|Fast
+|Excellent
+|Better compression
+
+|Zstandard
+|Very Fast
+|Very Fast
+|Very Good
+|Maximum speed
+
+|PPMd
+|Very Slow
+|Slow
+|Excellent
+|Text files only
+|===
+
+== Advanced Options
+
+=== Window Size
+
+Deflate uses a 32 KB sliding window:
+
+[source,ruby]
+----
+# Standard Deflate (32 KB window)
+Omnizip.compress_file('file.txt', 'output.zip',
+  compression: :deflate,
+  window_size: 32768  # 32 KB (standard)
+)
+
+# For smaller files, smaller window may be faster
+# Dictionary size is fixed at 32 KB for compatibility
+----
+
+=== Strategy Selection
+
+Deflate supports different compression strategies:
+
+[source,ruby]
+----
+# Default strategy (LZ77 + Huffman)
+compression_strategy: :default  # Best for most data
+
+# Filtered (better for image data)
+compression_strategy: :filtered
+
+# Huffman only (faster, less compression)
+compression_strategy: :huffman_only
+
+# RLE (good for repetitive data)
+compression_strategy: :rle
+----
+
+== Common Use Cases
+
+=== Quick Backups
+
+[source,ruby]
+----
+# Fast backup for frequent snapshots
+Omnizip.compress_directory(
+  '/var/www/app/',
+  "backup_#{Date.today}.zip",
+  compression: :deflate,
+  level: 3  # Fast compression
+)
+----
+
+=== Data Distribution
+
+[source,ruby]
+----
+# Package for distribution (broad compatibility)
+Omnizip::Archive.create('release-v1.0.zip', format: :zip) do |archive|
+  archive.compression = :deflate
+  archive.level = 9  # Best compression
+  archive.add_directory('dist/')
+end
+----
+
+=== Web Uploads
+
+Process uploads quickly:
+
+[source,ruby]
+----
+# Handle user uploads efficiently
+uploaded_files.each do |file|
+  Omnizip::Archive.create("#{user_id}-upload.zip", format: :zip) do |archive|
+    archive.compression = :deflate
+    archive.level = 6  # Balanced
+    archive.add_data(file.original_filename, file.read)
+  end
+end
+----
+
+== Compatibility
+
+=== Tool Support
+
+Deflate is supported by all major archive tools:
+
+* **7-Zip**: Full support (read/write)
+* **WinZip**: Native support
+* **WinRAR**: Full support
+* **Info-ZIP**: Native algorithm
+* **macOS Archive Utility**: Native support
+* **Windows Explorer**: Native support
+
+=== Format Support
+
+Deflate works in multiple formats:
+
+* **ZIP**: Primary compression method (method ID 8)
+* **7z**: Available as alternative to LZMA
+* **GZIP**: Single-file compression
+* **PNG**: Image compression
+
+== Technical Specifications
+
+* **Algorithm**: LZ77 dictionary compression + Huffman coding
+* **Window Size**: 32 KB (fixed)
+* **Match Length**: 3-258 bytes
+* **Based On**: Phil Katz's PKZip algorithm
+* **RFC**: RFC 1951 (DEFLATE specification)
+* **Implementation**: Uses Ruby's zlib library (native C)
+
+== Optimization Tips
+
+. **Use Level 6 for General Use**: Good balance of speed and compression
+. **Level 1 for Temporary Files**: When speed matters most
+. **Level 9 for Distribution**: When size matters more than time
+. **Monitor Throughput**: Deflate should process 5-15 MB/s
+. **Consider Deflate64**: For better compression (if compatible)
+
+== See Also
+
+* link:deflate64.html[Deflate64] - Enhanced Deflate with larger window
+* link:zstandard.html[Zstandard] - Modern fast compression
+* link:lzma2.html[LZMA2] - Better compression at cost of speed
+* link:../../compatibility.html[Compatibility] - Deflate support across tools