omnizip 0.3.1

data/readme-docs/archive-formats.adoc

@@ -0,0 +1,479 @@
+= Archive Formats
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Omnizip supports multiple archive formats with full read/write capabilities. This document provides detailed usage examples for each supported format.
+
+== Supported Formats
+
+[cols="20,20,20,40",options="header"]
+|===
+|Format |Read |Write |Notes
+
+|**7z**
+|✅
+|✅
+|Full support, solid compression, split archives
+
+|**ZIP**
+|✅
+|✅
+|ZIP64, WinZip AES, full compatibility
+
+|**RAR**
+|✅
+|🟡
+|Read RAR3/RAR5, write via external WinRAR
+
+|**TAR**
+|✅
+|✅
+|POSIX extensions, permissions, links
+
+|**ISO 9660**
+|✅
+|✅
+|Rock Ridge, Joliet, CD/DVD images
+
+|**CPIO**
+|✅
+|✅
+|newc, CRC formats, initramfs
+
+|**GZIP**
+|✅
+|✅
+|Single file compression
+
+|**XZ**
+|✅
+|✅
+|LZMA2-based format
+
+|**BZIP2**
+|✅
+|✅
+|Single file compression
+|===
+
+== 7-Zip Format (.7z)
+
+=== Creating 7z Archives
+
+[source,ruby]
+----
+# Basic 7z archive
+Omnizip::Formats::SevenZip::Writer.new('archive.7z') do |sz|
+  sz.add_file('file1.txt')
+  sz.add_file('file2.dat')
+  sz.add_directory('folder/')
+end
+
+# With compression options
+Omnizip::Formats::SevenZip::Writer.new('archive.7z',
+  algorithm: :lzma2,
+  level: 9,
+  solid: true
+) do |sz|
+  sz.add_directory('data/')
+end
+
+# With password encryption
+Omnizip::Formats::SevenZip::Writer.new('secure.7z',
+  password: 'secret123',
+  encrypt_header: true
+) do |sz|
+  sz.add_file('confidential.doc')
+end
+----
+
+=== Extracting 7z Archives
+
+[source,ruby]
+----
+# Extract all files
+Omnizip::Formats::SevenZip::Reader.open('archive.7z') do |sz|
+  sz.extract_all('output/')
+end
+
+# Extract with password
+Omnizip::Formats::SevenZip::Reader.open('secure.7z',
+  password: 'secret123'
+) do |sz|
+  sz.extract_all('output/')
+end
+
+# List contents
+Omnizip::Formats::SevenZip::Reader.open('archive.7z') do |sz|
+  sz.entries.each do |entry|
+    puts "#{entry.name}: #{entry.size} bytes"
+  end
+end
+----
+
+=== Split Archives (Multi-volume)
+
+[source,ruby]
+----
+# Create split archive (100MB volumes)
+Omnizip::Formats::SevenZip::SplitArchiveWriter.new('archive.7z',
+  volume_size: 100 * 1024 * 1024
+) do |sz|
+  sz.add_directory('large_dataset/')
+end
+# Creates: archive.7z.001, archive.7z.002, etc.
+
+# Extract split archive
+Omnizip::Formats::SevenZip::SplitArchiveReader.open('archive.7z.001') do |sz|
+  sz.extract_all('output/')  # Auto-reads all volumes
+end
+----
+
+== ZIP Format
+
+=== Creating ZIP Archives
+
+[source,ruby]
+----
+# Basic ZIP
+Omnizip::Formats::Zip::Writer.open('archive.zip') do |zip|
+  zip.add_file('file.txt')
+  zip.add_directory('data/')
+end
+
+# With WinZip AES encryption
+Omnizip::Formats::Zip::Writer.open('secure.zip',
+  password: 'secret',
+  encryption: :aes256
+) do |zip|
+  zip.add_file('private.doc')
+end
+
+# ZIP64 for large archives
+Omnizip::Formats::Zip::Writer.open('large.zip',
+  zip64: true
+) do |zip|
+  zip.add_file('huge_file.bin')  # >4GB file
+end
+----
+
+=== Extracting ZIP Archives
+
+[source,ruby]
+----
+# Extract ZIP
+Omnizip::Formats::Zip::Reader.open('archive.zip') do |zip|
+  zip.extract_all('output/')
+end
+
+# Extract with password
+Omnizip::Formats::Zip::Reader.open('secure.zip',
+  password: 'secret'
+) do |zip|
+  zip.extract_all('output/')
+end
+----
+
+== RAR Format
+
+=== Extracting RAR Archives
+
+[source,ruby]
+----
+# Extract RAR (read-only)
+Omnizip::Formats::Rar::Reader.open('archive.rar') do |rar|
+  rar.extract_all('output/')
+end
+
+# Multi-volume RAR
+Omnizip::Formats::Rar::Reader.open('archive.part001.rar') do |rar|
+  rar.extract_all('output/')  # Handles all .part00N.rar files
+end
+
+# With password
+Omnizip::Formats::Rar::Reader.open('secure.rar',
+  password: 'secret'
+) do |rar|
+  rar.extract_all('output/')
+end
+----
+
+=== Creating RAR Archives (External)
+
+[source,ruby]
+----
+# Requires licensed WinRAR installation
+if Omnizip::Formats::Rar::ExternalWriter.available?
+  writer = Omnizip::Formats::Rar::ExternalWriter.new('archive.rar',
+    license_confirmed: true,
+    compression_level: 5
+  )
+  
+  writer.add_file('file.txt')
+  writer.write
+else
+  puts "WinRAR not installed. Use 7z format instead:"
+  # Create 7z archive as alternative
+end
+----
+
+== TAR Format
+
+=== Creating TAR Archives
+
+[source,ruby]
+----
+# Basic TAR
+Omnizip::Formats::Tar::Writer.open('archive.tar') do |tar|
+  tar.add_file('file.txt')
+  tar.add_directory('data/', recursive: true)
+end
+
+# Preserve permissions
+Omnizip::Formats::Tar::Writer.open('backup.tar',
+  preserve_permissions: true
+) do |tar|
+  tar.add_file('/etc/config')
+  tar.add_symlink('link', '/path/to/target')
+end
+----
+
+=== Extracting TAR Archives
+
+[source,ruby]
+----
+# Extract TAR
+Omnizip::Formats::Tar::Reader.open('archive.tar') do |tar|
+  tar.extract_all('output/')
+end
+----
+
+=== Combined TAR+Compression
+
+[source,ruby]
+----
+# Create .tar.gz
+require 'zlib'
+File.open('archive.tar.gz', 'wb') do |gz_file|
+  Zlib::GzipWriter.wrap(gz_file) do |gz|
+    Omnizip::Formats::Tar::Writer.new(gz) do |tar|
+      tar.add_directory('data/')
+    end
+  end
+end
+
+# Create .tar.xz
+Omnizip::Formats::Xz.compress_stream do |xz|
+  Omnizip::Formats::Tar::Writer.new(xz) do |tar|
+    tar.add_directory('data/')
+  end
+end
+----
+
+== ISO 9660 Format
+
+=== Creating ISO Images
+
+[source,ruby]
+----
+# Basic ISO
+Omnizip::Formats::Iso::Writer.new('disk.iso',
+  volume_label: 'MY_DISK'
+) do |iso|
+  iso.add_file('README.txt')
+  iso.add_directory('docs/', recursive: true)
+  iso.write
+end
+
+# With Rock Ridge (Unix metadata)
+Omnizip::Formats::Iso::Writer.new('backup.iso',
+  rock_ridge: true
+) do |iso|
+  iso.add_directory('/home/user/data', recursive: true)
+  iso.write
+end
+
+# With Joliet (long filenames, Unicode)
+Omnizip::Formats::Iso::Writer.new('unicode.iso',
+  joliet: true,
+  volume_label: '日本語ディスク'
+) do |iso|
+  iso.add_file('文書.txt')
+  iso.write
+end
+----
+
+=== Extracting ISO Images
+
+[source,ruby]
+----
+# Extract ISO
+Omnizip::Formats::Iso::Reader.open('disk.iso') do |iso|
+  iso.extract_all('output/')
+end
+
+# List ISO contents
+Omnizip::Formats::Iso::Reader.open('disk.iso') do |iso|
+  iso.entries.each do |entry|
+    puts "#{entry.name}: #{entry.size} bytes"
+  end
+end
+----
+
+== CPIO Format
+
+=== Creating CPIO Archives
+
+[source,ruby]
+----
+# Create CPIO (newc format)
+Omnizip::Formats::Cpio::Writer.new('archive.cpio',
+  format: :newc
+) do |cpio|
+  cpio.add_file('file.txt')
+  cpio.add_directory('data/')
+  cpio.write
+end
+
+# CPIO with CRC
+Omnizip::Formats::Cpio::Writer.new('archive.cpio',
+  format: :crc
+) do |cpio|
+  cpio.add_file('important.dat')
+  cpio.write
+end
+
+# For initramfs
+Omnizip::Formats::Cpio::Writer.new('initramfs.cpio',
+  format: :newc
+) do |cpio|
+  cpio.add_directory('/boot/initramfs/', recursive: true)
+  cpio.write
+end
+----
+
+=== Extracting CPIO Archives
+
+[source,ruby]
+----
+# Extract CPIO
+Omnizip::Formats::Cpio::Reader.new('archive.cpio') do |cpio|
+  cpio.extract_all('output/')
+end
+----
+
+== Single-File Formats
+
+=== GZIP
+
+[source,ruby]
+----
+# Compress file
+Omnizip::Formats::Gzip.compress('input.txt', 'output.txt.gz')
+
+# Decompress file
+Omnizip::Formats::Gzip.decompress('output.txt.gz', 'restored.txt')
+
+# With compression level
+Omnizip::Formats::Gzip.compress('data.txt', 'data.txt.gz', level: 9)
+----
+
+=== XZ (LZMA2)
+
+[source,ruby]
+----
+# Compress file
+Omnizip::Formats::Xz.compress('input.txt', 'output.txt.xz')
+
+# Decompress file
+Omnizip::Formats::Xz.decompress('output.txt.xz', 'restored.txt')
+
+# With high compression
+Omnizip::Formats::Xz.compress('large.dat', 'large.dat.xz', level: 9)
+----
+
+=== BZIP2
+
+[source,ruby]
+----
+# Compress file
+Omnizip::Formats::Bzip2File.compress('input.txt', 'output.txt.bz2')
+
+# Decompress file
+Omnizip::Formats::Bzip2File.decompress('output.txt.bz2', 'restored.txt')
+
+# With compression level
+Omnizip::Formats::Bzip2File.compress('data.txt', 'data.txt.bz2', level: 9)
+----
+
+== Format Comparison
+
+[cols="15,15,15,15,40",options="header"]
+|===
+|Format |Compression |Speed |Size |Best For
+
+|**7z**
+|Excellent
+|Slow
+|Smallest
+|Maximum compression, solid archives
+
+|**ZIP**
+|Good
+|Fast
+|Medium
+|Compatibility, wide support
+
+|**RAR**
+|Excellent
+|Medium
+|Small
+|Read-only, recovery records
+
+|**TAR**
+|None*
+|Very Fast
+|Large
+|Unix backups, containers
+
+|**ISO**
+|None
+|Fast
+|Large
+|CD/DVD images, bootable media
+
+|**CPIO**
+|None*
+|Very Fast
+|Large
+|initramfs, RPM packages
+
+|**GZIP**
+|Good
+|Fast
+|Medium
+|Quick compression, streaming
+
+|**XZ**
+|Excellent
+|Slow
+|Smallest
+|Maximum compression, single files
+
+|**BZIP2**
+|Very Good
+|Medium
+|Small
+|Good balance, text files
+|===
+
+_* TAR and CPIO are container formats, combine with GZIP/XZ/BZIP2 for compression_
+
+== See Also
+
+* link:compression-profiles.adoc[Compression Profiles]
+* link:format-converter.adoc[Format Converter]
+* link:par2-archives.adoc[PAR2 Archives]
+* link:../README.adoc[Main README]

data/readme-docs/cli-usage.adoc

@@ -0,0 +1,222 @@
+= Command-Line Interface Usage
+:toc:
+:toclevels: 3
+
+== Purpose
+
+This document provides comprehensive CLI documentation for using Omnizip from the command line. The CLI is built using Thor and provides commands for compression, decompression, and archive operations.
+
+== General
+
+The `omnizip` command provides utilities for compressing and decompressing files.
+
+The CLI is built using Thor and provides four main commands: `compress`, `decompress`, `list`, and `version`. All commands support a `--verbose` flag for detailed output.
+
+== Available Commands
+
+Get help on available commands:
+
+[source,sh]
+----
+$ omnizip help
+Commands:
+  omnizip archive create ARCHIVE FILES...  # Create an archive
+  omnizip archive extract ARCHIVE [DIR]    # Extract an archive
+  omnizip archive list ARCHIVE             # List archive contents
+  omnizip compress INPUT OUTPUT            # Compress a file
+  omnizip decompress INPUT OUTPUT          # Decompress a file
+  omnizip help [COMMAND]                   # Describe available commands
+  omnizip list                             # List available algorithms
+  omnizip version                          # Display version information
+----
+
+[[compress-command]]
+== Compressing Files
+
+Compress a file using the LZMA algorithm:
+
+[source,sh]
+----
+# Basic compression with default settings (level 5)
+$ omnizip compress input.txt output.lzma
+Compressed: input.txt -> output.lzma
+
+# Compress with maximum compression (level 9)
+$ omnizip compress input.txt output.lzma --level 9
+
+# Compress with verbose output
+$ omnizip compress input.txt output.lzma --level 7 --verbose
+Compressing input.txt to output.lzma...
+Algorithm: lzma, Level: 7
+
+Input size:  1024000 bytes
+Output size: 245760 bytes
+Ratio:       76.0%
+Time:        1.23s
+----
+
+Get detailed help for the compress command:
+
+[source,sh]
+----
+$ omnizip help compress
+Usage:
+  omnizip compress INPUT OUTPUT
+
+Options:
+  [--algorithm=ALGORITHM]  # Compression algorithm to use
+                           # Default: lzma
+  [--level=N]             # Compression level (1-9)
+                          # Default: 5
+  -v, [--verbose]         # Enable verbose output
+
+Description:
+  Compress INPUT file and write the result to OUTPUT file.
+----
+
+[[decompress-command]]
+== Decompressing Files
+
+Decompress a compressed file:
+
+[source,sh]
+----
+# Basic decompression
+$ omnizip decompress output.lzma restored.txt
+Decompressed: output.lzma -> restored.txt
+
+# Decompress with verbose output
+$ omnizip decompress output.lzma restored.txt --verbose
+Decompressing output.lzma to restored.txt...
+Algorithm: lzma (auto-detected)
+
+Output size: 1024000 bytes
+Time:        0.45s
+----
+
+Get detailed help for the decompress command:
+
+[source,sh]
+----
+$ omnizip help decompress
+Usage:
+  omnizip decompress INPUT OUTPUT
+
+Options:
+  [--algorithm=ALGORITHM]  # Decompression algorithm
+                           # (auto-detect if omitted)
+  -v, [--verbose]         # Enable verbose output
+
+Description:
+  Decompress INPUT file and write the result to OUTPUT file.
+----
+
+[[list-command]]
+== Listing Available Algorithms
+
+List all registered compression algorithms:
+
+[source,sh]
+----
+$ omnizip list
+Available compression algorithms:
+
+lzma
+  Description: LZMA compression using range coding and dictionary compression
+  Version: 1.0.0
+----
+
+[[archive-commands]]
+== Archive Operations
+
+=== Creating Archives
+
+Create a .7z archive from multiple files:
+
+[source,sh]
+----
+# Create archive with default settings (LZMA2)
+$ omnizip archive create myfiles.7z file1.txt file2.bin directory/
+
+# Create with specific algorithm
+$ omnizip archive create --algorithm lzma myfiles.7z *.txt
+
+# Create with password protection
+$ omnizip archive create --password secret myfiles.7z sensitive.doc
+
+# Create with filters for executables
+$ omnizip archive create --filter bcj_x86 programs.7z *.exe
+
+# Verbose output
+$ omnizip archive create --verbose archive.7z data/
+Creating archive.7z...
+Adding: data/file1.txt (1.2 MB)
+Adding: data/file2.bin (3.4 MB)
+Algorithm: LZMA2, Compression: Level 5
+Total: 2 files, 4.6 MB → 1.8 MB (60.9% reduction)
+----
+
+=== Extracting Archives
+
+Extract files from a .7z archive:
+
+[source,sh]
+----
+# Extract to current directory
+$ omnizip archive extract myfiles.7z
+
+# Extract to specific directory
+$ omnizip archive extract myfiles.7z output/
+
+# Extract password-protected archive
+$ omnizip archive extract --password secret encrypted.7z
+
+# Verbose extraction
+$ omnizip archive extract --verbose archive.7z
+Extracting archive.7z...
+Extracting: data/file1.txt (1.2 MB)
+Extracting: data/file2.bin (3.4 MB)
+Total: 2 files extracted
+----
+
+=== Listing Archive Contents
+
+View contents of an archive:
+
+[source,sh]
+----
+$ omnizip archive list myfiles.7z
+Archive: myfiles.7z
+Files: 3
+
+Name                    Size        Compressed  Ratio   Modified
+────────────────────────────────────────────────────────────────
+file1.txt               1048576     245760      76.6%   2025-11-15
+file2.bin               3538944     892416      74.8%   2025-11-15
+directory/readme.md     2048        1024        50.0%   2025-11-14
+────────────────────────────────────────────────────────────────
+Total:                  4589568     1139200     75.2%
+----
+
+== Version Information
+
+Display version information:
+
+[source,sh]
+----
+$ omnizip version
+Omnizip v1.0.0
+Pure Ruby implementation of 7-Zip algorithms
+
+# Short form
+$ omnizip -v
+Omnizip v1.0.0
+Pure Ruby implementation of 7-Zip algorithms
+----
+
+== See Also
+
+* link:api-usage.adoc[Library API Usage]
+* link:compression-algorithms.adoc[Compression Algorithms]
+* link:archive-formats.adoc[Archive Formats]
+* link:../README.adoc[Main README]