omnizip 0.4.7-arm-linux

data/docs/guides/creating-archives.adoc

@@ -0,0 +1,348 @@
+---
+title: Creating Archives
+nav_order: 1
+parent: Guides
+---
+
+== Creating Archives
+
+Step-by-step guide to creating archives with Omnizip.
+
+== Quick Examples
+
+=== Create ZIP Archive
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip::Archive.create('backup.zip') do |archive|
+  archive.add_file('document.pdf')
+  archive.add_directory('photos/')
+end
+----
+
+=== Create 7z Archive
+
+[source,ruby]
+----
+Omnizip::Archive.create('backup.7z', format: :seven_zip) do |archive|
+  archive.add_directory('data/')
+end
+----
+
+=== Create RAR5 Archive
+
+[source,ruby]
+----
+require 'omnizip/formats/rar/rar5/writer'
+
+# STORE compression (uncompressed)
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar')
+writer.add_file('document.txt')
+writer.add_file('image.png')
+writer.write
+
+# LZMA compression (default level 3)
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
+  compression: :lzma
+)
+writer.add_file('large_dataset.json')
+writer.write
+
+# LZMA level 5 (best compression)
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
+  compression: :lzma,
+  level: 5
+)
+writer.add_directory('photos/')
+writer.write
+
+# Include modification time
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
+  include_mtime: true
+)
+writer.add_file('document.txt')
+writer.write
+
+# Include CRC32 (STORE compression only)
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
+  compression: :store,
+  include_crc32: true
+)
+writer.add_file('data.bin')
+writer.write
+----
+
+IMPORTANT: RAR5 CRC32 checksums only work with STORE compression. When LZMA is used, CRC32 is automatically disabled. Use BLAKE2sp (always present) for compressed file integrity.
+
+=== RAR5 Multi-Volume Archives
+
+Split large archives across multiple volumes:
+
+[source,ruby]
+----
+require 'omnizip/formats/rar/rar5/writer'
+
+# Basic multi-volume with default naming (part1, part2, ...)
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('backup.rar',
+  multi_volume: true,
+  volume_size: '100M'  # Human-readable sizes supported
+)
+writer.add_directory('large_dataset/')
+volumes = writer.write
+# => ['backup.part1.rar', 'backup.part2.rar', ...]
+
+# Custom volume naming patterns
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('data.rar',
+  multi_volume: true,
+  volume_size: '4.7GB',  # CD/DVD sizes
+  volume_naming: 'numeric'  # data.001.rar, data.002.rar, ...
+)
+writer.add_file('huge_database.sql')
+volumes = writer.write
+
+# Volume naming options:
+# - 'part' (default): archive.part1.rar, archive.part2.rar
+# - 'volume': archive.volume1.rar, archive.volume2.rar
+# - 'numeric': archive.001.rar, archive.002.rar
+
+# Minimum volume size: 64 KB
+----
+
+=== RAR5 Solid Archives
+
+`solid: true` requests a shared solid block, but the RAR-compatible
+LZSS encoder is not implemented yet — the writer warns and writes
+independent STORE entries instead, so the archive stays extractable
+by official unrar:
+
+[source,ruby]
+----
+require 'omnizip/formats/rar/rar5/writer'
+
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('project.rar',
+  solid: true  # warns: falls back to independent STORE entries
+)
+writer.add_directory('source_code/')
+writer.write
+----
+
+Solid compression (shared dictionary across files, better ratios
+for similar content) arrives when the RAR-compatible LZSS encoder
+lands.
+----
+
+=== RAR5 AES-256 Encryption
+
+Password-protect archives with industry-standard encryption:
+
+[source,ruby]
+----
+require 'omnizip/formats/rar/rar5/writer'
+
+# Basic password protection
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('secure.rar',
+  compression: :lzma,
+  password: 'SecurePassword123!'
+)
+writer.add_file('confidential.pdf')
+writer.write
+
+# Custom key derivation iterations (higher = more secure, slower)
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('protected.rar',
+  compression: :lzma,
+  level: 5,
+  password: 'VerySecurePassword2025!',
+  kdf_iterations: 524_288  # 2^19, more secure than default
+)
+writer.add_directory('sensitive_data/')
+writer.write
+
+# KDF iteration options:
+# - 65,536 (2^16): Minimum, fast but less secure
+# - 262,144 (2^18): Default, balanced security/performance
+# - 1,048,576 (2^20): Maximum, strongest security
+
+# Security features:
+# - AES-256-CBC encryption with PKCS#7 padding
+# - PBKDF2-HMAC-SHA256 key derivation
+# - Per-file IV generation
+# - Password verification before decryption
+----
+
+=== RAR5 PAR2 Recovery Records
+
+Add error correction for archive recovery:
+
+[source,ruby]
+----
+require 'omnizip/formats/rar/rar5/writer'
+
+# Enable PAR2 recovery with default 5% redundancy
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('backup.rar',
+  compression: :lzma,
+  recovery: true
+)
+writer.add_directory('important_data/')
+files = writer.write
+# => ['backup.rar', 'backup.par2', 'backup.vol00+01.par2', ...]
+
+# Custom redundancy percentage
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('critical.rar',
+  compression: :lzma,
+  level: 5,
+  recovery: true,
+  recovery_percent: 15  # Can recover up to 15% data loss
+)
+writer.add_file('mission_critical.db')
+files = writer.write
+
+# Redundancy guidelines:
+# - 5% (default): General backups
+# - 10%: Important data
+# - 20-30%: High-value data
+# - 50-100%: Maximum protection
+
+# Recovery capabilities:
+# - Detect corruption at block level
+# - Repair damaged archives automatically
+# - Works with multi-volume, solid, and encrypted archives
+----
+
+=== RAR5 Combined Features
+
+Use all features together for comprehensive protection:
+
+[source,ruby]
+----
+require 'omnizip/formats/rar/rar5/writer'
+
+# Production-ready backup configuration
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('complete_backup.rar',
+  # Compression
+  compression: :lzma,
+  level: 5,
+  solid: true,
+
+  # Security
+  password: 'SecureBackup2025!',
+  kdf_iterations: 262_144,
+
+  # Multi-volume
+  multi_volume: true,
+  volume_size: '4G',  # DVD-sized volumes
+  volume_naming: 'part',
+
+  # Recovery
+  recovery: true,
+  recovery_percent: 10,
+
+  # Optional fields
+  include_mtime: true
+)
+
+writer.add_directory('/critical/data')
+writer.add_directory('/important/documents')
+files = writer.write
+
+puts "Backup created: #{files.size} files"
+archive_files = files.select { |f| f.end_with?('.rar') }
+par2_files = files.select { |f| f.include?('.par2') }
+puts "  Archive volumes: #{archive_files.size}"
+puts "  PAR2 files: #{par2_files.size}"
+puts "  Total size: #{files.sum { |f| File.size(f) } / 1024 / 1024}MB"
+----
+
+=== RAR5 Best Practices
+
+**For Maximum Compatibility:**
+[source,ruby]
+----
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
+  compression: :lzma,
+  level: 5,        # Honored by the 7z-style writers; RAR5 entries
+                   # are STORE until the LZSS encoder lands
+  include_mtime: true
+)
+----
+
+**For Important Data:**
+[source,ruby]
+----
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('backup.rar',
+  compression: :lzma,
+  level: 3,              # Balanced performance
+  recovery: true,
+  recovery_percent: 15,  # 15% redundancy
+  include_mtime: true
+)
+----
+
+**For Optical Media:**
+[source,ruby]
+----
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
+  compression: :lzma,
+  level: 5,
+  solid: true,
+  multi_volume: true,
+  volume_size: '4.7GB',  # DVD size
+  recovery: true,
+  include_mtime: true
+)
+----
+
+**For Secure Archives:**
+[source,ruby]
+----
+writer = Omnizip::Formats::Rar::Rar5::Writer.new('secure.rar',
+  compression: :lzma,
+  level: 5,
+  password: ENV['BACKUP_PASSWORD'],
+  kdf_iterations: 524_288,  # Enhanced security
+  recovery: true,
+  recovery_percent: 10,
+  include_mtime: true
+)
+----
+
+== Adding Files
+
+=== Individual Files
+
+[source,ruby]
+----
+archive.add_file('source.txt', 'dest.txt')
+----
+
+=== Directories
+
+[source,ruby]
+----
+archive.add_directory('folder/')
+----
+
+=== From Data
+
+[source,ruby]
+----
+archive.add_data('config.json', JSON.generate(config))
+----
+
+== Compression Options
+
+[source,ruby]
+----
+Omnizip::Archive.create('archive.7z',
+                        format: :seven_zip,
+                        algorithm: :lzma2,
+                        level: 9) do |archive|
+  # ...
+end
+----
+
+== See Also
+
+* link:extracting-archives.html[Extracting Archives]
+* link:../reference/api/overview.html[Ruby API]

data/docs/guides/extracting-archives.adoc

@@ -0,0 +1,53 @@
+---
+title: Extracting Archives
+nav_order: 2
+parent: Guides
+---
+
+== Extracting Archives
+
+Guide to extracting files from archives.
+
+== Quick Examples
+
+=== Extract All Files
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip::Archive.open('backup.zip') do |archive|
+  archive.extract_all('output/')
+end
+----
+
+=== Extract Specific Files
+
+[source,ruby]
+----
+Omnizip::Archive.open('backup.zip') do |archive|
+  archive.extract('document.pdf', 'restored/document.pdf')
+end
+----
+
+=== List Contents
+
+[source,ruby]
+----
+entries = Omnizip.list_archive('backup.zip')
+entries.each do |entry|
+  puts "#{entry.name}: #{entry.size} bytes"
+end
+----
+
+== Pattern Matching
+
+[source,ruby]
+----
+archive.extract_matching('*.txt', 'output/')
+----
+
+== See Also
+
+* link:creating-archives.html[Creating Archives]
+* link:../reference/api/overview.html[Ruby API]

data/docs/guides/format-conversion.adoc

@@ -0,0 +1,64 @@
+---
+title: Format Conversion
+nav_order: 3
+parent: Guides
+---
+
+== Format Conversion
+
+Converting archives between different formats.
+
+== ZIP to 7z
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip::Archive.open('input.zip') do |zip_archive|
+  Omnizip::Archive.create('output.7z', format: :seven_zip) do |sevenz_archive|
+    zip_archive.entries.each do |entry|
+      next if entry.directory?
+      data = zip_archive.read(entry.name)
+      sevenz_archive.add_data(entry.name, data)
+    end
+  end
+end
+----
+
+== 7z to ZIP
+
+[source,ruby]
+----
+Omnizip::Archive.open('input.7z') do |sevenz_archive|
+  Omnizip::Archive.create('output.zip', format: :zip) do |zip_archive|
+    sevenz_archive.entries.each do |entry|
+      next if entry.directory?
+      data = sevenz_archive.read(entry.name)
+      zip_archive.add_data(entry.name, data)
+    end
+  end
+end
+----
+
+== Batch Conversion
+
+[source,ruby]
+----
+Dir.glob('*.zip').each do |zip_file|
+  sevenz_file = zip_file.sub('.zip', '.7z')
+
+  Omnizip::Archive.open(zip_file) do |src|
+    Omnizip::Archive.create(sevenz_file, format: :seven_zip, level: 9) do |dest|
+      src.entries.each do |entry|
+        next if entry.directory?
+        dest.add_data(entry.name, src.read(entry.name))
+      end
+    end
+  end
+end
+----
+
+== See Also
+
+* link:creating-archives.html[Creating Archives]
+* link:../comparison/feature-matrix.html[Format Comparison]

data/docs/guides/index.adoc

@@ -0,0 +1,49 @@
+---
+title: Guides
+nav_order: 10
+has_children: true
+---
+
+== Guides
+
+Comprehensive guides for all Omnizip features and formats.
+
+=== Core Operations
+
+* link:creating-archives.html[Creating Archives] - Build new archives with comprehensive examples
+* link:extracting-archives.html[Extracting Archives] - Extract files from archives
+* link:format-conversion.html[Format Conversion] - Convert between archive formats
+
+=== Compression Algorithms
+
+* link:compression-algorithms/[Compression Algorithms Overview] - Algorithm comparison and selection guide
+* link:compression-algorithms/lzma.html[LZMA] - High compression ratio algorithm
+* link:compression-algorithms/lzma2.html[LZMA2] - Enhanced LZMA with multi-threading
+* link:compression-algorithms/bzip2.html[BZip2] - Text file compression
+* link:compression-algorithms/ppmd.html[PPMd] - Prediction by Partial Matching for text
+* link:compression-algorithms/deflate.html[Deflate] - ZIP-compatible compression
+* link:compression-algorithms/zstandard.html[Zstandard] - Modern fast compression
+
+=== Archive Formats
+
+* link:archive-formats/[Archive Formats Overview] - Format comparison and selection guide
+* link:archive-formats/seven-zip-format.html[7z Format] - 7-Zip archives with solid compression
+* link:archive-formats/zip-format.html[ZIP Format] - ZIP archives with ZIP64 support
+* link:archive-formats/rar-format.html[RAR Format] - RAR4/RAR5 archives (read-only)
+* link:archive-formats/tar-format.html[TAR Format] - TAR archives with POSIX extensions
+* link:archive-formats/gzip-format.html[GZIP Format] - GZIP single file compression
+* link:archive-formats/xz-format.html[XZ Format] - XZ compressed files with LZMA2
+
+=== Advanced Features
+
+* link:advanced-features/[Advanced Features Overview] - Power user features
+* link:advanced-features/streaming.html[Streaming Operations] - Memory-efficient processing
+* link:advanced-features/parallel-processing.html[Parallel Processing] - Multi-threaded compression
+* link:advanced-features/progress-tracking.html[Progress Tracking] - Real-time progress monitoring
+* link:advanced-features/encryption.html[Encryption] - AES-256 password protection
+
+=== Migration & Optimization
+
+* link:migration-rubyzip.html[Migrating from Rubyzip] - Migration guide for rubyzip users
+* link:performance-tuning.html[Performance Tuning] - Optimize compression performance
+* link:parity-archives.html[PAR2 Parity Archives] - Error correction and recovery