omnizip 0.4.9-arm-linux → 0.4.11-arm-linux

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

@@ -1,124 +0,0 @@
----
-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

@@ -1,142 +0,0 @@
----
-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

@@ -1,105 +0,0 @@
----
-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

@@ -1,160 +0,0 @@
----
-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

@@ -1,151 +0,0 @@
----
-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)