omnizip 0.3.1

data/docs/guides/advanced-features/streaming.adoc

@@ -0,0 +1,212 @@
+---
+title: Streaming Operations
+nav_order: 1
+parent: Advanced Features
+grand_parent: Guides
+---
+
+== Purpose
+
+Streaming operations allow you to process archives without loading entire files into memory. This is essential for handling large archives, web applications, and memory-constrained environments.
+
+== Benefits
+
+* **Memory Efficient**: Process multi-GB archives with minimal memory footprint
+* **Fast Response**: Start processing immediately without waiting for complete download
+* **Scalable**: Handle archives of any size on servers with limited resources
+* **Web-Friendly**: Perfect for Rails applications and API services
+
+== When to Use Streaming
+
+[cols="1,3"]
+|===
+|Scenario |Streaming Benefit
+
+|Large Archives (>100MB)
+|Avoid loading entire archive into memory
+
+|Web Applications
+|Process uploads without temporary files
+
+|API Services
+|Stream responses directly to clients
+
+|Limited Memory
+|Process on resource-constrained servers
+
+|Network Transfers
+|Start processing while downloading
+|===
+
+== Creating Archives with Streaming
+
+=== Stream to File
+
+Create archives by streaming entries one at a time:
+
+[source,ruby]
+----
+Omnizip::OutputStream.open('backup.zip', format: :zip) do |stream|
+  # Add files as you go - no need to collect them first
+  Dir.glob('logs/*.log').each do |file|
+    stream.put_next_entry(File.basename(file))
+    File.open(file, 'rb') do |f|
+      stream.write(f.read)
+    end
+  end
+end
+----
+
+=== Stream to Memory
+
+Create archives in memory for immediate use:
+
+[source,ruby]
+----
+zip_data = Omnizip::OutputStream.write_buffer(format: :zip) do |stream|
+  stream.put_next_entry('report.txt')
+  stream.write(generate_report)
+
+  stream.put_next_entry('data.json')
+  stream.write(export_data.to_json)
+end
+
+# Send directly over HTTP
+send_data zip_data.string, filename: 'export.zip'
+----
+
+== Reading Archives with Streaming
+
+=== Extract While Reading
+
+Process each file as it's read from the archive:
+
+[source,ruby]
+----
+Omnizip::InputStream.open('large-archive.zip') do |stream|
+  while entry = stream.get_next_entry
+    next if entry.directory?
+
+    # Process each file immediately
+    case entry.name
+    when /\.csv$/
+      import_csv_data(stream.read)
+    when /\.json$/
+      process_json(stream.read)
+    end
+  end
+end
+----
+
+=== Selective Extraction
+
+Extract only specific files without reading the entire archive:
+
+[source,ruby]
+----
+Omnizip::InputStream.open('backup.zip') do |stream|
+  while entry = stream.get_next_entry
+    # Only extract configuration files
+    if entry.name.start_with?('config/')
+      File.open(entry.name, 'wb') do |f|
+        f.write(stream.read)
+      end
+    end
+  end
+end
+----
+
+== Web Application Examples
+
+=== Rails Upload Processing
+
+Process uploaded archives without temporary files:
+
+[source,ruby]
+----
+class ArchiveController < ApplicationController
+  def upload
+    uploaded = params[:archive]
+
+    # Process upload stream directly
+    files = Omnizip::Buffer.extract_all_to_memory(uploaded.read)
+
+    files.each do |filename, content|
+      # Process each file
+      process_file(filename, content)
+    end
+
+    render json: { processed: files.count }
+  end
+end
+----
+
+=== API Response Streaming
+
+Generate and stream archives in API responses:
+
+[source,ruby]
+----
+get '/export' do
+  content_type 'application/zip'
+  attachment 'export.zip'
+
+  stream do |out|
+    buffer = Omnizip::OutputStream.write_buffer do |zip|
+      User.find_each do |user|
+        zip.put_next_entry("#{user.id}.json")
+        zip.write(user.to_json)
+      end
+    end
+
+    out << buffer.string
+  end
+end
+----
+
+== Performance Characteristics
+
+[cols="2,1,1,1"]
+|===
+|Operation |Traditional |Streaming |Improvement
+
+|100MB Archive
+|100MB RAM
+|~10MB RAM
+|90% reduction
+
+|1GB Archive
+|1GB RAM
+|~10MB RAM
+|99% reduction
+
+|Web Upload
+|Temp file required
+|No temp file
+|Faster response
+
+|Large Extraction
+|Full parse first
+|Start immediately
+|Better UX
+|===
+
+== Best Practices
+
+. **Use Streaming for Large Files**: Any archive >50MB should use streaming
+. **Process Incrementally**: Don't collect all data before processing
+. **Handle Errors Gracefully**: Stream operations can fail mid-process
+. **Clean Up Resources**: Always use blocks to ensure cleanup
+. **Monitor Memory**: Verify memory stays constant during processing
+
+== Limitations
+
+* Cannot seek backwards in stream (forward-only processing)
+* Some operations require random access (use file-based API for those)
+* Central directory must fit in memory (usually small)
+
+== See Also
+
+* link:parallel-processing.html[Parallel Processing] - Combine with streaming for maximum performance
+* link:progress-tracking.html[Progress Tracking] - Monitor streaming operations
+* link:../../compatibility.html[Compatibility] - Streaming support across formats

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

@@ -0,0 +1,107 @@
+---
+title: GZIP Format
+nav_order: 5
+parent: Archive Formats
+grand_parent: Guides
+---
+
+== Purpose
+
+GZIP is the standard compression format on Unix/Linux systems for single files. It uses the Deflate algorithm and is widely supported across all platforms.
+
+== Key Characteristics
+
+[cols="1,3"]
+|===
+|Property |Value
+
+|Compression
+|Deflate
+
+|Encryption
+|None
+
+|Archive Support
+|Single file only (use with TAR for multiple files)
+
+|Large Files
+|Yes
+
+|Best For
+|Single file compression, web servers, Unix systems
+|===
+
+== Basic Usage
+
+=== Compress a File
+
+[source,ruby]
+----
+# Compress single file
+Omnizip.compress_file('data.txt', 'data.txt.gz')
+
+# With compression level
+Omnizip.compress_file('data.txt', 'data.txt.gz',
+  level: 9  # Maximum compression
+)
+----
+
+=== Decompress a File
+
+[source,ruby]
+----
+# Decompress GZIP file
+Omnizip.decompress_file('data.txt.gz', 'data.txt')
+
+# Decompress to automatically named file
+Omnizip.decompress_file('data.txt.gz')  # Creates data.txt
+----
+
+== GZIP vs Other Formats
+
+[cols="2,1,1,1"]
+|===
+|Feature |GZIP |XZ |ZIP
+
+|Compression
+|Good
+|Excellent
+|Good
+
+|Speed
+|Fast
+|Slow
+|Fast
+
+|Archive Support
+|No
+|No
+|Yes
+
+|Unix Standard
+|Yes
+|Growing
+|No
+|===
+
+== Streaming Compression
+
+GZIP supports streaming for large files:
+
+[source,ruby]
+----
+# Stream compress large file
+File.open('large.bin', 'rb') do |input|
+  Omnizip::Gzip::Writer.open('large.bin.gz') do |output|
+    while chunk = input.read(65536)
+      output.write(chunk)
+    end
+  end
+end
+----
+
+== See Also
+
+* link:tar-format.html[TAR Format] - Multi-file archives with GZIP
+* link:xz-format.html[XZ Format] - Better compression alternative
+* link:deflate.html[Deflate Algorithm] - Compression algorithm details

data/docs/guides/archive-formats/index.adoc

@@ -0,0 +1,130 @@
+---
+title: Archive Formats
+nav_order: 20
+parent: Guides
+has_children: true
+---
+
+== Archive Formats Overview
+
+Omnizip supports 10 archive formats for different use cases. Each format has unique features, compression options, and compatibility characteristics.
+
+== Format Comparison
+
+[cols="1,1,1,2"]
+|===
+|Format |Compression |Encryption |Best For
+
+|link:seven-zip-format.html[7z]
+|Multiple (LZMA2, etc.)
+|AES-256
+|Software distribution, backups
+
+|link:zip-format.html[ZIP]
+|Deflate, PPMd
+|AES (WinZip), Traditional
+|Cross-platform compatibility
+
+|link:rar-format.html[RAR]
+|RAR (proprietary)
+|AES-256
+|Binary distribution, multi-volume
+
+|link:tar-format.html[TAR]
+|External (gzip, bzip2, xz)
+|None
+|Unix backups, software packaging
+
+|link:gzip-format.html[GZIP]
+|Deflate
+|None
+|Single file compression
+
+|link:xz-format.html[XZ]
+|LZMA2
+|None
+|System package compression
+|===
+
+== Choosing a Format
+
+=== By Use Case
+
+[cols="1,2"]
+|===
+|Use Case |Recommended Format
+
+|Cross-platform distribution
+|ZIP (universal compatibility)
+
+|Maximum compression
+|7z with LZMA2 (level 9)
+
+|Large file splitting
+|RAR (multi-volume support) or 7z
+
+|Unix/Linux backups
+|TAR with XZ or BZip2
+
+|Single file compression
+|GZIP or XZ
+
+|Software packages
+|7z or TAR.XZ
+|===
+
+=== By Compatibility
+
+[cols="1,4"]
+|===
+|Platform |Best Format
+
+|Windows
+|ZIP (native), 7z (7-Zip), RAR (WinRAR)
+
+|macOS
+|ZIP (native), 7z, TAR.GZ
+
+|Linux
+|TAR.GZ, TAR.XZ, ZIP, 7z
+
+|Universal
+|ZIP (supported everywhere)
+|===
+
+== Format Features
+
+=== 7z Format
+
+* **Compression**: LZMA, LZMA2, BZip2, PPMd, Deflate, Zstandard
+* **Encryption**: AES-256 with header encryption
+* **Solid Archives**: Yes (better compression)
+* **Multi-Volume**: Yes
+* **Large Files**: Yes (up to 16 billion GB)
+
+=== ZIP Format
+
+* **Compression**: Deflate, Deflate64, PPMd, BZip2
+* **Encryption**: AES-256 (WinZip), Traditional (weak)
+* **ZIP64**: Yes (files >4GB)
+* **Universal Support**: Yes
+
+=== RAR Format
+
+* **Compression**: Proprietary RAR algorithm
+* **Encryption**: AES-256
+* **Multi-Volume**: Excellent support
+* **Recovery Records**: Error correction
+
+=== TAR Format
+
+* **Compression**: External (GZIP, BZip2, XZ)
+* **Encryption**: None
+* **POSIX**: Full support
+* **Unix Standard**: Yes
+
+== See Also
+
+* link:../compression-algorithms/[Compression Algorithms] - Choose the right compression
+* link:../../compatibility.html[Compatibility] - Detailed format support matrix
+* link:../advanced-features/encryption.html[Encryption] - Secure your archives

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

@@ -0,0 +1,104 @@
+---
+title: RAR Format
+nav_order: 3
+parent: Archive Formats
+grand_parent: Guides
+---
+
+== Purpose
+
+RAR is a proprietary archive format known for its excellent compression ratio and robust multi-volume support. Omnizip provides full read support for RAR4 and RAR5 archives.
+
+== Key Characteristics
+
+[cols="1,3"]
+|===
+|Property |Value
+
+|Compression
+|Proprietary RAR algorithm (excellent ratio)
+
+|Encryption
+|AES-256 (RAR5), AES-128 (RAR4)
+
+|Multi-Volume
+|Excellent support with recovery records
+
+|Error Recovery
+|Recovery records for damaged archives
+
+|Best For
+|Binary distribution, large archives, error-sensitive storage
+|===
+
+[IMPORTANT]
+====
+RAR compression is patented software. Omnizip can only **read** RAR archives, not create them. See link:../../RAR_WRITE_SUPPORT.html[RAR Write Support] for details.
+====
+
+== Reading RAR Archives
+
+=== Basic Extraction
+
+[source,ruby]
+----
+# Extract RAR archive
+Omnizip.extract_archive('backup.rar', 'output/')
+
+# List contents
+archive = Omnizip::Archive.open('backup.rar')
+archive.each_entry do |entry|
+  puts "#{entry.name} - #{entry.size} bytes"
+end
+----
+
+=== Encrypted Archives
+
+[source,ruby]
+----
+# Extract password-protected RAR
+Omnizip.extract_archive('secure.rar', 'output/',
+  password: 'your-password'
+)
+----
+
+=== Multi-Volume Archives
+
+[source,ruby]
+----
+# Extract multi-volume RAR (part1.rar, part2.rar, ...)
+Omnizip.extract_archive('archive.part1.rar', 'output/')
+----
+
+== RAR4 vs RAR5
+
+[cols="2,1,1"]
+|===
+|Feature |RAR4 |RAR5
+
+|Compression
+|Good
+|Excellent
+
+|Encryption
+|AES-128
+|AES-256
+
+|Dictionary Size
+|4 MB
+|Up to 1 GB
+
+|Multi-Threading
+|Limited
+|Full support
+
+|Recovery Records
+|Yes
+|Enhanced
+|===
+
+== See Also
+
+* link:seven-zip-format.html[7z Format] - Alternative for creating archives
+* link:zip-format.html[ZIP Format] - Universal compatibility
+* link:../../RAR_WRITE_SUPPORT.html[RAR Write Support] - Licensing information