omnizip 0.3.1

data/docs/index.adoc

@@ -0,0 +1,218 @@
+---
+title: Home
+nav_order: 0
+---
+
+== Omnizip: Pure Ruby compression library
+
+=== Purpose
+
+Omnizip is a comprehensive pure Ruby implementation of compression algorithms and archive formats. Built on an extensible, registry-based architecture with clean object-oriented design, Omnizip provides full-featured compression capabilities without external dependencies.
+
+This implementation supports multiple compression algorithms (LZMA, LZMA2, BZip2, PPMd7/8, Deflate, Deflate64, Zstandard), preprocessing filters (BCJ variants, Delta), encryption (AES-256), and complete support for multiple archive formats (.7z, ZIP, RAR, TAR, ISO, CPIO, GZIP, XZ, BZIP2).
+
+It provides both a command-line interface and a programmatic Ruby API, making it ideal for applications requiring portable, dependency-free compression without relying on system-level libraries or external binaries.
+
+**Pure Ruby Implementation:** Works on all Ruby platforms (MRI, JRuby, TruffleRuby) with zero external dependencies. Performance is 10-60x slower than native implementations, which is an acceptable trade-off for maximum portability.
+
+=== Quick Start
+
+Get started with Omnizip in minutes:
+
+* link:getting-started/installation.html[Install the gem and dependencies]
+* link:getting-started/quick-start.html[Compress your first file in 5 minutes]
+* link:getting-started/your-first-archive.html[Create your first archive]
+
+=== Documentation Map
+
+==== New to Omnizip?
+
+Follow this learning path:
+
+. Install Omnizip
+** link:getting-started/installation.html[Installation Guide]
+
+. Quick Start (5 minutes)
+** link:getting-started/quick-start.html[Quick Start Guide]
+
+. Create Your First Archive
+** link:getting-started/your-first-archive.html[Create Your First Archive]
+
+. Learn Basic Operations
+** link:guides/creating-archives.html[Create archives]
+** link:guides/extracting-archives.html[Extract from archives]
+
+==== Looking for Something Specific?
+
+**Working with Files**
+
+* link:guides/creating-archives.html[Create new archives]
+* link:guides/extracting-archives.html[Extract from archives]
+* link:guides/format-conversion.html[Convert between formats]
+
+**Compression Algorithms**
+
+* link:guides/compression-algorithms/lzma.html[LZMA/LZMA2 compression]
+* link:guides/compression-algorithms/bzip2.html[BZip2 compression]
+* link:guides/compression-algorithms/ppmd.html[PPMd7/PPMd8 compression]
+* link:guides/compression-algorithms/deflate.html[Deflate/Deflate64 compression]
+* link:guides/compression-algorithms/zstandard.html[Zstandard compression]
+
+**Archive Formats**
+
+* link:guides/archive-formats/seven-zip-format.html[7z archives]
+* link:guides/archive-formats/zip-format.html[ZIP archives]
+* link:guides/archive-formats/rar-format.html[RAR4/RAR5 archives]
+* link:guides/archive-formats/tar-format.html[TAR archives]
+* link:guides/archive-formats/gzip-format.html[GZIP files]
+* link:guides/archive-formats/xz-format.html[XZ files]
+
+**Advanced Features**
+
+* link:guides/advanced-features/streaming.html[Streaming operations]
+* link:guides/advanced-features/parallel-processing.html[Parallel processing]
+* link:guides/advanced-features/encryption.html[Encryption]
+* link:guides/parity-archives.html[PAR2 error correction]
+
+**Reference Materials**
+
+* link:resources/quick-reference.html[Cheat sheet for common operations]
+* link:reference/cli/overview.html[Command-line interface documentation]
+* link:reference/api/overview.html[Ruby API documentation]
+* link:concepts/index.html[Core concepts explained]
+* link:developer/architecture.html[Design and implementation details]
+
+=== Supported Compression Algorithms
+
+Omnizip supports 6 major compression algorithms:
+
+[cols="1,3,2"]
+|===
+|Algorithm |Description |Best For
+
+|LZMA/LZMA2
+|Dictionary-based compression with high ratio
+|Archives, backups, general compression
+
+|BZip2
+|Burrows-Wheeler Transform compression
+|Text files, source code
+
+|PPMd7/PPMd8
+|Prediction by Partial Matching
+|Text, documents, natural language
+
+|Deflate/Deflate64
+|ZIP-compatible compression
+|Cross-platform compatibility
+
+|Zstandard
+|Modern fast compression
+|Speed-sensitive applications
+|===
+
+=== Supported Archive Formats
+
+Omnizip supports 10 archive formats:
+
+[cols="1,3,2"]
+|===
+|Format |Description |Common Use
+
+|.7z
+|7-Zip archives with solid compression
+|Software distribution, backups
+
+|ZIP
+|ZIP archives with ZIP64 support
+|Cross-platform archives
+
+|RAR4/RAR5
+|RAR archives with multi-volume support
+|Binary distribution, file sharing
+
+|TAR
+|TAR archives with POSIX extensions
+|Unix backups, software packaging
+
+|ISO 9660
+|ISO optical disc images
+|CD/DVD images
+
+|CPIO
+|CPIO archives
+|Unix system backups
+
+|GZIP
+|GZIP compressed files
+|Single file compression
+
+|XZ
+|XZ compressed files with LZMA2
+|System package compression
+
+|BZIP2
+|BZIP2 compressed files
+|Text file compression
+|===
+
+=== Key Features
+
+* **Pure Ruby** - No native dependencies, works on any Ruby platform
+* **Registry-Based** - Extensible plugin architecture for algorithms and formats
+* **Multiple Formats** - Support for 10+ archive formats
+* **Compression Profiles** - Smart algorithm selection based on file type
+* **Solid Archives** - Shared dictionary for better compression ratios
+* **Multi-Volume** - Split archives across multiple files
+* **Encryption** - AES-256 password protection
+* **PAR2 Support** - Error correction and recovery records
+* **CLI Tools** - Complete command-line interface
+* **Ruby API** - Full programmatic access
+* **Enumerable** - All collections support Ruby's Enumerable interface
+
+=== Example Usage
+
+.Compressing a file
+[source,ruby]
+----
+require 'omnizip'
+
+# Simple one-liner
+Omnizip.compress_file('input.txt', 'output.zip')
+
+# With options
+Omnizip.compress_file('input.txt', 'output.lzma',
+  algorithm: :lzma,
+  level: 9
+)
+----
+
+.Command-line interface
+[source,bash]
+----
+# Compress a file
+omnizip compress input.txt output.lzma --level 9
+
+# Create a .7z archive
+omnizip archive create backup.7z documents/ photos/
+
+# Extract an archive
+omnizip archive extract backup.7z output/
+
+# List archive contents
+omnizip archive list backup.7z
+----
+
+=== Getting help
+
+* **Documentation**: Browse the guides and reference sections
+* **Issues**: Report bugs at https://github.com/metanorma/omnizip/issues
+* **Source**: View the code at https://github.com/metanorma/omnizip
+
+=== Related sections
+
+* link:getting-started/index.html[Installation and quick start]
+* link:guides/index.html[Comprehensive usage guides]
+* link:reference/index.html[API and CLI documentation]
+* link:concepts/index.html[Core concepts and architecture]
+* link:troubleshooting/index.html[Common problems and solutions]

data/docs/lychee.toml

@@ -0,0 +1,67 @@
+# Lychee Link Checker Configuration
+# For Omnizip Documentation
+# https://github.com/lycheeverse/lychee
+
+# Cache results to avoid re-checking same URLs
+cache = true
+max_cache_age = "1d"
+
+# Check both source files and built site
+include_verbatim = true
+
+# Recursively check all files
+recursive = true
+
+# File types to check
+include = [
+  "_site/**/*.html"
+]
+
+# Excluded paths
+exclude = [
+  ".git",
+  ".github",
+  "node_modules",
+  "vendor",
+  ".bundle",
+  ".sass-cache",
+  ".jekyll-cache"
+]
+
+# Link checking behavior
+max_redirects = 10
+max_retries = 3
+timeout = 20
+
+# Accept status codes
+accept = [
+  "100..=103",  # Informational
+  "200..=299",  # Success
+  "429"         # Too Many Requests (retry handled by max_retries)
+]
+
+# User agent to identify ourselves
+user_agent = "lychee/omnizip-docs-link-checker"
+
+# Check HTTP, HTTPS, and file:// schemes
+scheme = ["https", "http", "file"]
+
+# Include file:// URLs for local link checking
+include_file = true
+
+# Handle different link types
+include_mail = false  # Don't check mailto: links
+
+# Follow links but don't check their content recursively
+max_concurrency = 8
+
+# Verbose output for debugging
+verbose = "info"
+
+# Require HTTPS where possible
+require_https = false  # Don't enforce
+
+# Check fragment identifiers (anchors)
+# include_fragments = true
+
+index_files = ["index.html"]

data/docs/reference/api/overview.adoc

@@ -0,0 +1,188 @@
+---
+title: API Overview
+nav_order: 60
+parent: Reference
+---
+
+== Ruby API Overview
+
+=== General
+
+Omnizip provides a comprehensive Ruby API for all compression and archive operations.
+
+=== Requiring the Library
+
+[source,ruby]
+----
+require 'omnizip'
+----
+
+=== Convenience Methods
+
+==== File Operations
+
+[source,ruby]
+----
+# Compress a file
+Omnizip.compress_file('input.txt', 'output.lzma')
+
+# Decompress a file
+Omnizip.decompress_file('output.lzma', 'restored.txt')
+
+# Extract archive
+Omnizip.extract_archive('archive.7z', 'output/')
+
+# List archive contents
+Omnizip.list_archive('archive.7z')
+----
+
+==== Stream Operations
+
+[source,ruby]
+----
+# Compress streams
+File.open('input.txt', 'rb') do |input|
+  File.open('output.lzma', 'wb') do |output|
+    Omnizip.compress_stream(input, output)
+  end
+end
+
+# Decompress streams
+File.open('output.lzma', 'rb') do |input|
+  File.open('restored.txt', 'wb') do |output|
+    Omnizip.decompress_stream(input, output)
+  end
+end
+----
+
+=== Registry-Based API
+
+==== Algorithm Registry
+
+[source,ruby]
+----
+# List available algorithms
+Omnizip::AlgorithmRegistry.registered.each do |name|
+  puts "Algorithm: #{name}"
+end
+
+# Get algorithm instance
+lzma = Omnizip::AlgorithmRegistry.get(:lzma).new(level: 9)
+
+# Use algorithm
+File.open('input.txt', 'rb') do |input|
+  File.open('output.lzma', 'wb') do |output|
+    lzma.compress(input, output)
+  end
+end
+----
+
+==== Format Registry
+
+[source,ruby]
+----
+# List available formats
+Omnizip::FormatRegistry.registered.each do |name|
+  puts "Format: #{name}"
+end
+
+# Create format-specific writer
+writer = Omnizip::FormatRegistry.get(:seven_zip).new_writer('archive.7z')
+writer.add_file('document.txt')
+writer.close
+----
+
+=== Archive Operations
+
+==== Creating Archives
+
+[source,ruby]
+----
+# 7z archive
+writer = Omnizip::Formats::SevenZip::Writer.new('archive.7z')
+writer.add_file('document.txt')
+writer.add_directory('photos/')
+writer.close
+
+# ZIP archive
+writer = Omnizip::Formats::Zip::Writer.new('archive.zip')
+writer.add_file('document.txt')
+writer.close
+----
+
+==== Extracting Archives
+
+[source,ruby]
+----
+# 7z archive
+reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z')
+reader.extract_all('output/')
+reader.close
+
+# ZIP archive
+reader = Omnizip::Formats::Zip::Reader.new('archive.zip')
+reader.extract_all('output/')
+reader.close
+----
+
+==== Listing Contents
+
+[source,ruby]
+----
+reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z')
+reader.open
+reader.each_file do |entry|
+  puts "#{entry.name}: #{entry.size} bytes"
+end
+reader.close
+----
+
+=== Error Handling
+
+[source,ruby]
+----
+begin
+  Omnizip.compress_file('input.txt', 'output.lzma')
+rescue Omnizip::CompressionError => e
+  puts "Compression failed: #{e.message}"
+rescue Omnizip::AlgorithmNotFound => e
+  puts "Algorithm not found: #{e.message}"
+rescue IOError => e
+  puts "I/O error: #{e.message}"
+end
+----
+
+=== Progress Tracking
+
+[source,ruby]
+----
+# Create tracker with callback
+progress = Omnizip::ProgressTracker.new
+
+Omnizip.compress_file('large.txt', 'large.lzma',
+  progress_callback: ->(percent) {
+    puts "Progress: #{percent}%" if percent % 10 == 0
+  }
+)
+----
+
+=== Configuration
+
+[source,ruby]
+----
+# Set default compression level
+Omnizip.config.default_level = 7
+
+# Set default algorithm
+Omnizip.config.default_algorithm = :lzma2
+
+# Enable verbose output
+Omnizip.config.verbose = true
+----
+
+=== See Also
+
+* link:compression-api[Compression API] - Compression details
+* link:decompression-api[Decompression API] - Decompression details
+* link:archive-api[Archive API] - Archive operations
+* link:algorithm-registry[Algorithm Registry] - Algorithm management

data/docs/reference/cli/compress-command.adoc

@@ -0,0 +1,114 @@
+---
+title: compress - Compress Files
+nav_order: 52
+parent: Reference
+---
+
+== compress Command
+
+=== General
+
+Compress individual files using various compression algorithms.
+
+=== Syntax
+
+[source,bash]
+----
+omnizip compress [OPTIONS] INPUT OUTPUT
+----
+
+=== Arguments
+
+`INPUT`:: Input file path (use `-` for stdin)
+`OUTPUT`:: Output file path (use `-` for stdout)
+
+=== Options
+
+`--algorithm ALGORITHM`:: Compression algorithm (default: lzma)
+`--format FORMAT`:: Archive format (zip, 7z) for pipe mode
+`--level LEVEL`:: Compression level (1-9, default: 5)
+`--entry-name NAME`:: Entry name for pipe mode
+`--verbose`, `-v`:: Enable verbose output
+
+=== Examples
+
+==== Basic Compression
+
+[source,bash]
+----
+omnizip compress input.txt output.lzma
+----
+
+==== With Algorithm
+
+[source,bash]
+----
+# LZMA
+omnizip compress input.txt output.lzma --algorithm lzma
+
+# BZip2
+omnizip compress input.txt output.bz2 --algorithm bzip2
+
+# Zstandard
+omnizip compress input.txt output.zst --algorithm zstandard
+----
+
+==== With Level
+
+[source,bash]
+----
+# Fast
+omnizip compress input.txt output.lzma --level 1
+
+# Maximum
+omnizip compress input.txt output.lzma --level 9
+----
+
+==== Pipe Mode
+
+[source,bash]
+----
+# From stdin
+cat input.txt | omnizip compress - output.lzma
+
+# To stdout
+omnizip compress input.txt - > output.lzma
+
+# Full pipe
+cat input.txt | omnizip compress - - | other-command
+----
+
+==== With Format
+
+[source,bash]
+----
+# Create ZIP
+cat input.txt | omnizip compress - output.zip --format zip
+
+# Create 7z
+cat input.txt | omnizip compress - output.7z --format 7z
+----
+
+=== Algorithms
+
+Available algorithms:
+
+* `lzma` - LZMA compression
+* `lzma2` - LZMA2 compression (default)
+* `bzip2` - BZip2 compression
+* `ppmd7` - PPMd7 compression
+* `deflate` - Deflate compression
+* `zstandard` - Zstandard compression
+
+=== Performance Tips
+
+1. **Use level 1-3** for temporary files
+2. **Use level 5-7** for general compression
+3. **Use level 8-9** for long-term storage
+4. **Use Zstandard** for speed-sensitive applications
+5. **Use LZMA2** for maximum compression
+
+=== See Also
+
+* link:overview.html[CLI Overview] - Command-line interface
+* link:../api/overview.html[Ruby API Overview] - Programmatic interface

data/docs/reference/cli/overview.adoc

@@ -0,0 +1,140 @@
+---
+title: CLI Overview
+nav_order: 51
+parent: Reference
+---
+
+== Command-Line Interface Overview
+
+=== General
+
+Omnizip provides a comprehensive command-line interface for all compression and archive operations.
+
+=== Basic Syntax
+
+[source,bash]
+----
+omnizip [global-options] COMMAND [command-options] [arguments]
+----
+
+=== Global Options
+
+`--version`, `-v`:: Show version information
+`--help`, `-h`:: Show help message
+
+=== Available Commands
+
+==== Compression Commands
+
+* link:compress-command[`compress`] - Compress a file or stream
+* link:decompress-command[`decompress`] - Decompress a file or stream
+
+==== Archive Commands
+
+* link:archive-command[`archive create`] - Create an archive
+* link:archive-command[`archive extract`] - Extract an archive
+* link:archive-command[`archive list`] - List archive contents
+* link:archive-command[`archive metadata`] - View/edit archive metadata
+
+==== Utility Commands
+
+* link:list-command[`list`] - List available algorithms
+* link:profile-command[`profile`] - Manage compression profiles
+* link:convert-command[`convert`] - Convert between formats
+
+=== Common Patterns
+
+==== Pipe Mode
+
+Use `-` for stdin/stdout:
+
+[source,bash]
+----
+# Read from stdin
+cat input.txt | omnizip compress - output.lzma
+
+# Write to stdout
+omnizip compress input.txt - > output.lzma
+
+# Full pipe
+cat input.txt | omnizip compress - - | omnizip decompress - output.txt
+----
+
+==== Verbosity
+
+Enable detailed output with `--verbose`:
+
+[source,bash]
+----
+omnizip compress input.txt output.lzma --verbose
+----
+
+==== Compression Levels
+
+Most commands accept compression levels:
+
+[source,bash]
+----
+# Fast (1-3)
+omnizip compress input.txt output.lzma --level 1
+
+# Balanced (4-6)
+omnizip compress input.txt output.lzma --level 5
+
+# Maximum (7-9)
+omnizip compress input.txt output.lzma --level 9
+----
+
+=== Command Help
+
+Each command supports `--help`:
+
+[source,bash]
+----
+omnizip compress --help
+omnizip archive create --help
+omnizip profile list --help
+----
+
+=== Exit Codes
+
+* `0` - Success
+* `1` - Error occurred
+* `2` - Invalid command or options
+
+=== Environment Variables
+
+`OMNIZIP_LEVEL`:: Default compression level (1-9)
+`OMNIZIP_ALGORITHM`:: Default compression algorithm
+`OMNIZIP_THREADS`:: Number of threads for parallel operations
+
+=== Examples
+
+==== Quick Backup
+
+[source,bash]
+----
+# Create compressed backup
+omnizip archive create backup.7z documents/ --level 7
+
+# Verify
+omnizip archive list backup.7z
+
+# Extract to test
+omnizip archive extract backup.7z /tmp/test/
+----
+
+==== Batch Processing
+
+[source,bash]
+----
+# Compress all log files
+for log in *.log; do
+  omnizip compress "$log" "${log}.lzma" --level 5
+done
+----
+
+=== Related Sections
+
+* link:compress-command.html[compress command] - Compress files
+* link:../api/overview.html[Ruby API] - Programmatic interface