omnizip 0.3.1

data/docs/getting-started/basic-usage.adoc

@@ -0,0 +1,271 @@
+---
+title: Basic Usage
+nav_order: 3
+parent: Getting Started
+---
+
+== Basic Usage
+
+This guide covers common usage patterns and operations with Omnizip.
+
+== File Compression
+
+=== Compressing Files
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Basic compression
+Omnizip.compress_file('input.txt', 'output.lzma')
+
+# With specific algorithm
+Omnizip.compress_file('input.txt', 'output.bz2', algorithm: :bzip2)
+
+# With compression level (1-9)
+Omnizip.compress_file('input.txt', 'output.lzma', level: 9)
+----
+
+=== Decompressing Files
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Auto-detect algorithm
+Omnizip.decompress_file('compressed.lzma', 'restored.txt')
+
+# Specify algorithm explicitly
+Omnizip.decompress_file('compressed.bz2', 'restored.txt', algorithm: :bzip2)
+----
+
+== Archive Operations
+
+=== Creating Archives
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Create ZIP from directory
+Omnizip.compress_directory('my_folder/', 'backup.zip')
+
+# Create 7z archive
+Omnizip.compress_directory('my_folder/', 'backup.7z', format: :seven_zip)
+
+# Add individual files
+Omnizip::Archive.create('custom.zip') do |archive|
+  archive.add_file('file1.txt')
+  archive.add_file('file2.txt')
+  archive.add_directory('folder/')
+end
+----
+
+=== Extracting Archives
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Extract entire archive
+Omnizip.extract_archive('backup.zip', 'output/')
+
+# Extract with pattern matching
+Omnizip::Archive.open('backup.zip') do |archive|
+  archive.extract_matching('*.txt', 'output/')
+end
+----
+
+=== Reading Archive Contents
+
+[source,ruby]
+----
+require 'omnizip'
+
+# List all entries
+entries = Omnizip.list_archive('backup.zip')
+entries.each do |entry|
+  puts "#{entry.name}: #{entry.size} bytes"
+end
+
+# Read specific file without extraction
+content = Omnizip.read_from_archive('backup.zip', 'config.json')
+puts content
+----
+
+== Stream Processing
+
+=== In-Memory Compression
+
+[source,ruby]
+----
+require 'omnizip'
+require 'stringio'
+
+# Compress string data
+data = "Hello, World!" * 1000
+input = StringIO.new(data)
+output = StringIO.new
+
+algorithm = Omnizip::AlgorithmRegistry.get(:lzma).new(level: 5)
+algorithm.compress(input, output)
+
+compressed_data = output.string
+puts "Compressed: #{data.bytesize} → #{compressed_data.bytesize} bytes"
+----
+
+=== Streaming Large Files
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Stream compression for large files
+File.open('large_input.txt', 'rb') do |input|
+  File.open('large_output.lzma', 'wb') do |output|
+    algorithm = Omnizip::AlgorithmRegistry.get(:lzma).new
+    algorithm.compress(input, output)
+  end
+end
+----
+
+== Algorithm Selection
+
+=== Available Algorithms
+
+[source,ruby]
+----
+require 'omnizip'
+
+# List available algorithms
+puts Omnizip::AlgorithmRegistry.available.inspect
+# => [:lzma, :lzma2, :bzip2, :ppmd7, :ppmd8, :deflate, :deflate64, :zstd]
+
+# Get algorithm metadata
+lzma = Omnizip::AlgorithmRegistry.get(:lzma)
+metadata = lzma.metadata
+puts "#{metadata.name}: #{metadata.description}"
+----
+
+=== Algorithm Characteristics
+
+**LZMA/LZMA2**::
+Best compression ratio, slower speed. Use for maximum compression.
+
+**BZip2**::
+Good compression, moderate speed. Excellent for text files.
+
+**PPMd7/PPMd8**::
+Excellent for text compression. Statistical modeling.
+
+**Deflate/Deflate64**::
+ZIP-compatible. Fast compression, good for general use.
+
+**Zstandard**::
+Modern algorithm. Fast compression and decompression.
+
+== Error Handling
+
+=== Handling Compression Errors
+
+[source,ruby]
+----
+require 'omnizip'
+
+begin
+  Omnizip.compress_file('input.txt', 'output.lzma')
+rescue Omnizip::Error => e
+  puts "Compression failed: #{e.message}"
+rescue Errno::ENOENT => e
+  puts "File not found: #{e.message}"
+end
+----
+
+=== Verifying Archives
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Verify archive integrity
+begin
+  Omnizip::Archive.open('archive.zip') do |archive|
+    archive.verify
+  end
+  puts "Archive is valid"
+rescue Omnizip::CorruptArchiveError => e
+  puts "Archive is corrupted: #{e.message}"
+end
+----
+
+== Performance Tips
+
+=== Choosing Compression Level
+
+[source,ruby]
+----
+# Fast compression (level 1-3)
+Omnizip.compress_file('file.txt', 'fast.lzma', level: 1)
+
+# Balanced (level 4-6) - Default: 5
+Omnizip.compress_file('file.txt', 'balanced.lzma', level: 5)
+
+# Maximum compression (level 7-9)
+Omnizip.compress_file('file.txt', 'best.lzma', level: 9)
+----
+
+=== Memory-Efficient Processing
+
+[source,ruby]
+----
+# Use streaming for large files
+File.open('huge_file.txt', 'rb') do |input|
+  File.open('huge_file.lzma', 'wb') do |output|
+    algorithm = Omnizip::AlgorithmRegistry.get(:lzma).new
+    algorithm.compress(input, output)
+  end
+end
+# File is processed in chunks, not loaded entirely into memory
+----
+
+== Common Patterns
+
+=== Batch Compression
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Compress multiple files
+Dir.glob('*.txt').each do |file|
+  output = "#{file}.lzma"
+  Omnizip.compress_file(file, output, level: 7)
+  puts "Compressed: #{file} → #{output}"
+end
+----
+
+=== Temporary Archives
+
+[source,ruby]
+----
+require 'omnizip'
+require 'tempfile'
+
+# Create temporary archive
+Tempfile.create(['backup', '.zip']) do |tmpfile|
+  Omnizip::Archive.create(tmpfile.path) do |archive|
+    archive.add_directory('data/')
+  end
+
+  # Use archive...
+  puts "Temporary archive: #{tmpfile.path}"
+end
+# Archive is automatically deleted
+----
+
+== See Also
+
+* link:../guides/creating-archives.html[Creating Archives Guide]
+* link:../guides/extracting-archives.html[Extracting Archives Guide]
+* link:../guides/performance-tuning.html[Performance Tuning]
+* link:../reference/api/overview.html[Ruby API Reference]

data/docs/getting-started/index.adoc

@@ -0,0 +1,42 @@
+---
+title: Getting Started
+nav_order: 2
+has_children: true
+---
+
+== Getting Started with Omnizip
+
+Welcome to Omnizip! This section will help you get up and running quickly with Omnizip's compression and archiving features.
+
+== What You'll Learn
+
+This section covers:
+
+* **Installation** - How to install Omnizip in your environment
+* **Quick Start** - Your first compression operations in minutes
+* **Basic Usage** - Common operations and workflows
+
+== Prerequisites
+
+* Ruby 3.0 or later
+* Bundler (for project integration)
+* Basic familiarity with Ruby
+
+== Topics
+
+link:installation.html[**Installation**]::
+Install Omnizip via RubyGems or Bundler
+
+link:quick-start.html[**Quick Start**]::
+5-minute tutorial to get started with compression
+
+link:basic-usage.html[**Basic Usage**]::
+Common operations and usage patterns
+
+== Next Steps
+
+After completing the Getting Started guide, explore:
+
+* link:../guides/[How-To Guides] for specific tasks
+* link:../reference/[API Reference] for detailed documentation
+* link:../comparison/[Comparison] to see how Omnizip compares to other tools

data/docs/getting-started/installation.adoc

@@ -0,0 +1,138 @@
+---
+title: Installation
+nav_order: 1
+parent: Getting Started
+---
+
+== Installation
+
+=== General
+
+Install Omnizip to start working with compression algorithms and archive formats in Ruby.
+
+=== Requirements
+
+==== Ruby Version
+
+Omnizip requires Ruby 3.0 or higher:
+
+* MRI (Matz's Ruby Interpreter) 3.0+
+* JRuby 9.4+
+* TruffleRuby 22+
+
+Check your Ruby version:
+
+[source,bash]
+----
+ruby --version
+----
+
+==== Runtime Dependencies
+
+Omnizip has minimal dependencies:
+
+* `lutaml-model` (~> 0.7) - Model serialization
+* `marcel` (~> 1.0) - MIME type detection
+
+These are automatically installed with the gem.
+
+=== Installing via Bundler
+
+Add Omnizip to your Gemfile:
+
+[source,ruby]
+----
+# Gemfile
+gem 'omnizip'
+----
+
+Then install:
+
+[source,bash]
+----
+bundle install
+----
+
+=== Installing via RubyGems
+
+Install the gem directly:
+
+[source,bash]
+----
+gem install omnizip
+----
+
+=== Verifying Installation
+
+Verify that Omnizip is installed correctly:
+
+[source,bash]
+----
+# Check the gem is installed
+gem list omnizip
+
+# Check the version
+omnizip version
+
+# List available algorithms
+omnizip list
+----
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Check version
+puts Omnizip::VERSION
+
+# List algorithms
+Omnizip::AlgorithmRegistry.registered.each do |name|
+  puts "Algorithm: #{name}"
+end
+----
+
+=== Installing from Source
+
+To install from the source repository:
+
+[source,bash]
+----
+git clone https://github.com/metanorma/omnizip.git
+cd omnizip
+bundle install
+rake install
+----
+
+=== Development Installation
+
+For development or contributing:
+
+[source,bash]
+----
+git clone https://github.com/metanorma/omnizip.git
+cd omnizip
+bundle install
+bundle exec rake
+----
+
+=== Platform-Specific Notes
+
+==== Linux
+
+No special requirements. Works with system Ruby or rbenv/rvm-managed Ruby.
+
+==== macOS
+
+No special requirements. Works with system Ruby or rbenv/rvm-managed Ruby.
+
+==== Windows
+
+Works with Ruby for Windows or RubyInstaller. Some file operations may have path handling differences.
+
+=== Next Steps
+
+After installation:
+
+* link:quick-start[Quick Start Guide] - Get started in 5 minutes
+* link:your-first-archive[Create Your First Archive] - Build a practical example
+* link:../guides/basic-usage[Basic Usage Guide] - Learn common operations

data/docs/getting-started/quick-start.adoc

@@ -0,0 +1,185 @@
+---
+title: Quick Start
+nav_order: 2
+parent: Getting Started
+---
+
+== Quick Start
+
+=== General
+
+Get started with Omnizip in 5 minutes. This guide covers the most common operations.
+
+=== Installing Omnizip
+
+First, install the gem:
+
+[source,bash]
+----
+gem install omnizip
+----
+
+Or add to your Gemfile:
+
+[source,ruby]
+----
+gem 'omnizip'
+----
+
+Then run `bundle install`.
+
+=== Compressing a File
+
+==== Command Line
+
+[source,bash]
+----
+omnizip compress input.txt output.lzma --level 9
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip.compress_file('input.txt', 'output.lzma', level: 9)
+----
+
+=== Creating an Archive
+
+==== Command Line
+
+[source,bash]
+----
+omnizip archive create backup.7z documents/ photos/
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z')
+writer.add_directory('documents/')
+writer.add_directory('photos/')
+writer.close
+----
+
+=== Extracting an Archive
+
+==== Command Line
+
+[source,bash]
+----
+omnizip archive extract backup.7z output/
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
+reader.extract_all('output/')
+reader.close
+----
+
+=== Listing Archive Contents
+
+==== Command Line
+
+[source,bash]
+----
+omnizip archive list backup.7z
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
+reader.open
+reader.each_file do |entry|
+  puts "#{entry.name}: #{entry.size} bytes"
+end
+reader.close
+----
+
+=== Using Different Compression Algorithms
+
+==== LZMA (High Compression)
+
+[source,bash]
+----
+omnizip compress input.txt output.lzma --algorithm lzma --level 9
+----
+
+[source,ruby]
+----
+Omnizip.compress_file('input.txt', 'output.lzma',
+  algorithm: :lzma,
+  level: 9
+)
+----
+
+==== BZip2 (Text Files)
+
+[source,bash]
+----
+omnizip compress input.txt output.bz2 --algorithm bzip2 --level 9
+----
+
+[source,ruby]
+----
+Omnizip.compress_file('input.txt', 'output.bz2',
+  algorithm: :bzip2,
+  level: 9
+)
+----
+
+==== Zstandard (Fast)
+
+[source,bash]
+----
+omnizip compress input.txt output.zst --algorithm zstandard --level 3
+----
+
+[source,ruby]
+----
+Omnizip.compress_file('input.txt', 'output.zst',
+  algorithm: :zstandard,
+  level: 3
+)
+----
+
+=== Common Compression Levels
+
+[cols="1,2,2"]
+|===
+|Level |Speed |Ratio
+
+|0-1
+|Fastest
+|Low (2-3x)
+
+|3-5
+|Fast
+|Medium (3-5x)
+
+|7-9
+|Slow
+|High (5-10x)
+|===
+
+=== Next Steps
+
+* link:your-first-archive[Create Your First Archive] - More detailed examples
+* link:../guides/basic-usage[Basic Usage Guide] - Comprehensive operations guide
+* link:../guides/compression-algorithms/[Compression Algorithms] - Algorithm details
+* link:../reference/cli[CLI Reference] - Complete command documentation
+* link:../reference/api[API Reference] - Complete Ruby API documentation