omnizip 0.4.7-x86_64-linux

data/docs/guides/advanced-features/progress-tracking.adoc

@@ -0,0 +1,124 @@
+---
+title: Progress Tracking
+nav_order: 3
+parent: Advanced Features
+grand_parent: Guides
+---
+
+== Purpose
+
+Long compression and extraction jobs benefit from progress feedback.
+Omnizip ships a standalone tracker — +Omnizip::Progress+ — with
+percentage, throughput, and ETA calculation. The convenience methods
+do not emit progress themselves: wrap your own loop with a tracker.
+
+== Basic Tracking
+
+Create a tracker, update it as work completes, read live stats:
+
+[source,ruby]
+----
+tracker = Omnizip::Progress.track(total_files: 100, total_bytes: 1_000_000)
+
+tracker.update(files: 10, bytes: 100_000, current_file: "file.txt")
+
+tracker.percentage       # => 10.0
+tracker.elapsed_seconds
+tracker.eta_seconds
+tracker.eta_formatted    # => "2m 30s"
+----
+
+== Reporters
+
+=== Callback Reporter
+
+Yield progress to a block:
+
+[source,ruby]
+----
+tracker = Omnizip::Progress.track(total_files: 100,
+                                  total_bytes: 1_000_000) do |progress|
+  puts "#{progress.percentage}% complete"
+end
+----
+
+=== Console Reporter
+
+Render a terminal progress bar:
+
+[source,ruby]
+----
+tracker = Omnizip::Progress.track(
+  total_files: 100,
+  total_bytes: 1_000_000,
+  reporter: :console
+)
+----
+
+=== Log Reporter
+
+Write updates to a log file (pass the reporter instance):
+
+[source,ruby]
+----
+reporter = Omnizip::Progress::LogReporter.new(
+  log_file: 'compress.log', verbose: true
+)
+
+tracker = Omnizip::Progress.track(
+  total_files: 100,
+  total_bytes: 1_000_000,
+  reporter: reporter
+)
+----
+
+== Wrapping a Compression Job
+
+Track a directory compression file by file:
+
+[source,ruby]
+----
+files = Dir.glob('data/**/*').select { |f| File.file?(f) }
+tracker = Omnizip::Progress.track(
+  total_files: files.size,
+  total_bytes: files.sum { |f| File.size(f) },
+  reporter: :console
+)
+
+Omnizip::Archive.create('backup.zip') do |archive|
+  files.each do |file|
+    archive.add_file(file, file.delete_prefix('data/'))
+    tracker.update(files: 1, bytes: File.size(file), current_file: file)
+  end
+end
+----
+
+== Web Application Integration
+
+Broadcast progress from a background job:
+
+[source,ruby]
+----
+class ArchiveJob < ApplicationJob
+  def perform(user_id, file_paths)
+    tracker = Omnizip::Progress.track(total_files: file_paths.size)
+
+    file_paths.each_with_index do |path, i|
+      process_file(path)
+      tracker.update(files: 1, current_file: path)
+
+      ActionCable.server.broadcast("archive_#{user_id}", {
+        status: 'processing',
+        files_done: i + 1,
+        total_files: file_paths.size,
+        percentage: tracker.percentage
+      })
+    end
+  end
+end
+----
+
+== See Also
+
+* link:streaming.html[Streaming Operations] - Memory-efficient processing
+* link:parallel-processing.html[Parallel Processing] - Multi-core strategies

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

@@ -0,0 +1,142 @@
+---
+title: Streaming Operations
+nav_order: 1
+parent: Advanced Features
+grand_parent: Guides
+---
+
+== Purpose
+
+== 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.
+
+Omnizip's streaming classes live under +Omnizip::Zip+ (streaming is a ZIP feature; the 7z and TAR writers accept buffered adds through the link:../creating-archives.html[Archive facade]).
+
+== Creating Archives with Streaming
+
+=== Stream to File
+
+Create ZIP archives by streaming entries one at a time:
+
+[source,ruby]
+----
+require 'omnizip/zip/output_stream'
+
+Omnizip::Zip::OutputStream.open('backup.zip') do |stream|
+  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
+----
+
+Per-entry compression method and level are supported:
+
+[source,ruby]
+----
+stream.put_next_entry('data.bin', compression: :zstandard, level: 3)
+----
+
+=== Stream to Memory
+
+Create ZIP archives in memory with +Omnizip::Buffer+:
+
+[source,ruby]
+----
+zip_data = Omnizip::Buffer.create(:zip) do |archive|
+  archive.add('report.txt', generate_report)
+  archive.add('data.json', export_data.to_json)
+end
+
+send_data zip_data.read, filename: 'export.zip'  # StringIO
+
+# Or straight from a Hash
+zip_data = Omnizip::Buffer.create_from_hash(
+  'report.txt' => generate_report,
+  'data.json' => export_data.to_json
+)
+----
+
+== Reading Archives with Streaming
+
+=== Extract While Reading
+
+Process each file as it's read from the archive:
+
+[source,ruby]
+----
+require 'omnizip/zip/input_stream'
+
+Omnizip::Zip::InputStream.open('large-archive.zip') do |stream|
+  while (entry = stream.get_next_entry)
+    next if entry.directory?
+
+    case entry.name
+    when /\.csv$/
+      import_csv_data(stream.read)
+    when /\.json$/
+      process_json(stream.read)
+    end
+  end
+end
+----
+
+=== Extract to Memory
+
+Read all entries into a Hash without touching the filesystem:
+
+[source,ruby]
+----
+files = Omnizip::Buffer.extract_to_memory(File.binread('backup.zip'))
+
+files.each do |filename, content|
+  process_file(filename, content)
+end
+----
+
+== Web Application Examples
+
+=== Rails Upload Processing
+
+[source,ruby]
+----
+class ArchiveController < ApplicationController
+  def upload
+    uploaded = params[:archive]
+
+    files = Omnizip::Buffer.extract_to_memory(uploaded.read)
+
+    files.each do |filename, content|
+      process_file(filename, content)
+    end
+
+    render json: { processed: files.count }
+  end
+end
+----
+
+=== API Response Streaming
+
+[source,ruby]
+----
+get '/export' do
+  content_type 'application/zip'
+  attachment 'export.zip'
+
+  zip_data = Omnizip::Buffer.create(:zip) do |archive|
+    User.find_each do |user|
+      archive.add("#{user.id}.json", user.to_json)
+    end
+  end
+
+  zip_data.read
+end
+----
+
+== See Also
+
+* link:parallel-processing.html[Parallel Processing] - Multi-core strategies
+* link:../creating-archives.html[Creating Archives] - Block-style archive facade

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

@@ -0,0 +1,105 @@
+---
+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|
+  File.open('large.bin.gz', 'wb') do |output|
+    Omnizip::Formats::Gzip.compress_stream(input, output)
+  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,160 @@
+---
+title: Archive Formats
+nav_order: 20
+parent: Guides
+has_children: true
+---
+
+== Archive Formats Overview
+
+Omnizip supports 12 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
+
+|link:rpm-format.html[RPM]
+|gzip, bzip2, xz, zstd
+|GPG signatures
+|Linux package management
+
+|link:ole-format.html[OLE]
+|None (internal structure)
+|Document-specific
+|Windows compound files, MSI
+|===
+
+== 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
+
+|Linux package management
+|RPM
+
+|Windows compound documents
+|OLE (MSI, DOC, XLS, PPT)
+|===
+
+=== 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
+
+=== RPM Format
+
+* **Compression**: gzip, bzip2, xz, zstd (payload)
+* **Encryption**: GPG signatures
+* **Payload**: CPIO archive
+* **Metadata**: Rich package information
+
+=== OLE Format
+
+* **Structure**: FAT-like file system
+* **Streams**: Multiple streams and sub-storages
+* **Types**: MSI, DOC, XLS, PPT, MSG
+* **Metadata**: Summary information streams
+
+== 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/ole-format.adoc

@@ -0,0 +1,151 @@
+---
+title: OLE Format
+nav_order: 10
+parent: Archive Formats
+grand_parent: Guides
+---
+
+[[ole-format]]
+== Purpose
+
+OLE (Object Linking and Embedding) Compound Document format is used
+by Microsoft for storing structured data in a single file. Common OLE
+files include MSI (Windows Installer packages), DOC (legacy Word),
+XLS (legacy Excel), PPT (legacy PowerPoint) and THM (theme) files.
+
+The API is stream-oriented: open the compound document, list
+streams and storages by path, and read the streams you need.
+
+== Basic Usage
+
+=== Open an OLE File
+
+[source,ruby]
+----
+# Open OLE compound document (block form closes automatically)
+Omnizip::Formats::Ole.open('document.doc') do |ole|
+  puts ole.list.inspect
+end
+
+# Non-block form: close explicitly
+ole = Omnizip::Formats::Ole.open('document.doc')
+ole.close
+----
+
+=== List Entries
+
+[source,ruby]
+----
+# Top-level streams and storages
+Omnizip::Formats::Ole.list('document.doc')
+
+# Inside a nested storage
+Omnizip::Formats::Ole.list('document.doc', '/ObjectPool')
+----
+
+=== Read Stream Data
+
+[source,ruby]
+----
+# \x01SummaryInformation holds document metadata
+summary = Omnizip::Formats::Ole.read('document.doc',
+                                     "\x01SummaryInformation")
+puts "Summary size: #{summary.bytesize} bytes"
+
+# WordDocument stream (main content)
+content = Omnizip::Formats::Ole.read('document.doc', 'WordDocument')
+puts "Document content size: #{content.bytesize} bytes"
+
+# Write a stream to disk
+File.binwrite('workbook.bin',
+              Omnizip::Formats::Ole.read('spreadsheet.xls', 'Workbook'))
+----
+
+=== Entry Introspection
+
+[source,ruby]
+----
+info = Omnizip::Formats::Ole.info('document.doc', 'WordDocument')
+puts info.inspect
+
+Omnizip::Formats::Ole.exist?('document.doc', 'WordDocument') # => true
+Omnizip::Formats::Ole.file?('document.doc', 'WordDocument')  # => true
+Omnizip::Formats::Ole.directory?('document.doc', 'ObjectPool') # => true
+----
+
+== MSI Package Inspection
+
+MSI files are OLE compound documents; the installer tables live in
+storages and streams you can walk with +list+:
+
+[source,ruby]
+----
+Omnizip::Formats::Ole.open('installer.msi') do |msi|
+  msi.list('/').each { |entry| puts entry }
+  summary = msi.read("\x05SummaryInformation") rescue nil
+  tables = msi.read('_Tables') rescue nil
+  puts "Tables stream size: #{tables&.bytesize}" if tables
+end
+----
+
+== Storage Structure
+
+OLE files have a hierarchical structure like a file system:
+
+----
+Root Storage/
+├── \x01SummaryInformation     (document metadata)
+├── WordDocument              (main content)
+├── Data/
+│   └── Mso1Table
+└── ObjectPool/
+    └── Ole10Native
+----
+
+Stream paths use `/` separators (e.g. +"ObjectPool/Ole10Native"+).
+
+== File Format Detection
+
+OLE files carry the signature +D0 CF 11 E0 A1 B1 1A E1+ in the first
+8 bytes:
+
+[source,ruby]
+----
+File.open('document.doc', "rb") do |f|
+  magic = f.read(8)
+  ole = magic == "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b
+  puts(ole ? "OLE compound document" : "not OLE")
+end
+----
+
+== Supported File Types
+
+[cols="2,1,1"]
+|===
+|Format |Extension |Read Support
+
+|Microsoft Word
+|.doc
+|Yes
+
+|Microsoft Excel
+|.xls
+|Yes
+
+|Microsoft PowerPoint
+|.ppt
+|Yes
+
+|Windows Installer
+|.msi
+|Yes
+
+|Generic OLE
+|.ole
+|Yes
+|===
+
+== See Also
+
+* link:seven-zip-format.html[7z Format] - Can contain OLE files
+* link:zip-format.html[ZIP Format] - Modern Office uses ZIP (docx, xlsx, pptx)