omnizip 0.3.37 → 0.3.39

data/docs/guides/archive-formats/ole-format.adoc

@@ -8,37 +8,13 @@ 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 documents)
-- XLS (legacy Excel spreadsheets)
-- PPT (legacy PowerPoint presentations)
-- THM (Microsoft Theme files)
-- MSG (Outlook messages)
+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.
 
-OLE uses a FAT-like file system within a single file, supporting up to 4GB of structured data.
-
-== Key Characteristics
-
-[cols="1,3"]
-|===
-|Property |Value
-
-|Max Size
-|2GB (standard), 4GB (with 4KB sectors)
-
-|Sector Sizes
-|512 bytes (standard), 4KB (large)
-
-|Streams
-|Multiple streams and sub-storages
-
-|Encryption
-|Optional (document-specific)
-
-|Best For
-|Windows compound files, legacy Office documents, MSI installers
-|===
+The API is stream-oriented: open the compound document, list
+streams and storages by path, and read the streams you need.
 
 == Basic Usage
 
@@ -46,189 +22,104 @@ OLE uses a FAT-like file system within a single file, supporting up to 4GB of st
 
 [source,ruby]
 ----
-# Open OLE compound document
-ole = Omnizip::Ole.open('document.doc')
-
-# Access root storage
-root = ole.root
-puts "Root storage: #{root.name}"
-
-# List streams and storages
-root.each do |entry|
-  puts "#{entry.name} (#{entry.size} bytes)" if entry.file?
-  puts "#{entry.name}/" if entry.directory?
+# 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]
 ----
-# Read a specific stream
-ole = Omnizip::Ole.open('document.doc')
-
-# Access \x01SummaryInformation stream (document metadata)
-summary = ole.open_stream("\x01SummaryInformation")
-if summary
-  data = summary.read
-  puts "Summary size: #{data.size} bytes"
-end
+# \x01SummaryInformation holds document metadata
+summary = Omnizip::Formats::Ole.read('document.doc',
+                                     "\x01SummaryInformation")
+puts "Summary size: #{summary.bytesize} bytes"
 
-# Access WordDocument stream (main content)
-word_stream = ole.open_stream("WordDocument")
-if word_stream
-  content = word_stream.read
-  puts "Document content size: #{content.size} bytes"
-end
+# WordDocument stream (main content)
+content = Omnizip::Formats::Ole.read('document.doc', 'WordDocument')
+puts "Document content size: #{content.bytesize} bytes"
 
-ole.close
+# Write a stream to disk
+File.binwrite('workbook.bin',
+              Omnizip::Formats::Ole.read('spreadsheet.xls', 'Workbook'))
 ----
 
-=== Extract All Files
+=== Entry Introspection
 
 [source,ruby]
 ----
-# Extract all streams from OLE to files
-Omnizip::Ole.open('document.doc') do |ole|
-  ole.extract_to('/output/directory/')
-end
+info = Omnizip::Formats::Ole.info('document.doc', 'WordDocument')
+puts info.inspect
 
-# Extract specific stream
-Omnizip::Ole.open('spreadsheet.xls') do |ole|
-  workbook = ole.open_stream('Workbook')
-  File.binwrite('workbook.bin', workbook.read)
-end
+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 containing Windows Installer data:
+MSI files are OLE compound documents; the installer tables live in
+storages and streams you can walk with +list+:
 
 [source,ruby]
 ----
-# Open MSI package
-msi = Omnizip::Ole.open('installer.msi')
-
-# List MSI tables (storages)
-tables = msi.root.select { |e| e.directory? }
-puts "MSI Tables:"
-tables.each { |t| puts "  #{t.name}" }
-
-# Access \x05SummaryInformation
-summary = msi.open_stream("\x05SummaryInformation")
-if summary
-  puts "Summary information found"
+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
-
-# Access _Tables stream (list of all tables)
-tables_stream = msi.open_stream("_Tables")
-if tables_stream
-  puts "Tables stream size: #{tables_stream.size}"
-end
-
-msi.close
 ----
 
 == Storage Structure
 
 OLE files have a hierarchical structure like a file system:
 
-[source]
 ----
 Root Storage/
 ├── \x01SummaryInformation     (document metadata)
-├── \x01DocumentSummaryInformation
 ├── WordDocument              (main content)
-├── 1Table                    (data tables)
 ├── Data/
-│   ├── Mso1Table
-│   └── Mso0Table
+│   └── Mso1Table
 └── ObjectPool/
-    └── _1000000000/
-        └── Ole10Native
-----
-
-[source,ruby]
-----
-# Navigate storage hierarchy
-ole = Omnizip::Ole.open('document.doc')
-
-# Access nested storage
-pool = ole.root.find("ObjectPool")
-if pool
-  pool.each do |entry|
-    puts "ObjectPool/#{entry.name}"
-  end
-end
-
-ole.close
-----
-
-== Summary Information
-
-OLE documents contain standard metadata streams:
-
-[source,ruby]
+    └── Ole10Native
 ----
-# Read summary information
-ole = Omnizip::Ole.open('document.doc')
-
-# Access summary stream
-summary_stream = ole.open_stream("\x01SummaryInformation")
-if summary_stream
-  # Summary information is in a specific binary format
-  # Omnizip provides helpers to decode it
-  summary = ole.summary_information
-  if summary
-    puts "Title: #{summary.title}"
-    puts "Author: #{summary.author}"
-    puts "Subject: #{summary.subject}"
-    puts "Keywords: #{summary.keywords}"
-    puts "Created: #{summary.create_time}"
-    puts "Modified: #{summary.last_save_time}"
-  end
-end
 
-ole.close
-----
+Stream paths use `/` separators (e.g. +"ObjectPool/Ole10Native"+).
 
 == File Format Detection
 
-OLE files can be identified by their signature:
+OLE files carry the signature +D0 CF 11 E0 A1 B1 1A E1+ in the first
+8 bytes:
 
 [source,ruby]
 ----
-# Check if file is OLE
-File.open('document.doc', 'rb') do |f|
-  header = f.read(8)
-  if Omnizip::Ole.ole_signature?(header)
-    puts "This is an OLE compound document"
-  end
-end
-
-# Get OLE file type
-ole = Omnizip::Ole.open('document.doc')
-case ole.file_type
-when :word_document
-  puts "Microsoft Word document"
-when :excel_spreadsheet
-  puts "Microsoft Excel spreadsheet"
-when :powerpoint
-  puts "Microsoft PowerPoint presentation"
-when :msi_package
-  puts "Windows Installer package"
-else
-  puts "Unknown OLE type: #{ole.file_type}"
+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
-ole.close
 ----
 
 == Supported File Types
 
-Omnizip supports reading the following OLE-based formats:
-
 [cols="2,1,1"]
 |===
 |Format |Extension |Read Support
@@ -249,67 +140,11 @@ Omnizip supports reading the following OLE-based formats:
 |.msi
 |Yes
 
-|Microsoft Theme
-|.thm
-|Yes
-
-|Outlook Message
-|.msg
-|Yes
-
 |Generic OLE
 |.ole
 |Yes
 |===
 
-== Low-Level Access
-
-For advanced use cases, you can access the OLE internals directly:
-
-[source,ruby]
-----
-# Access BAT (Block Allocation Table)
-ole = Omnizip::Ole.open('document.doc')
-
-# Get sector size
-puts "Sector size: #{ole.sector_size}"
-
-# Access BAT entries
-bat = ole.bat
-puts "BAT entries: #{bat.size}"
-
-# Access SBAT (Small Block Allocation Table)
-sbat = ole.sbat
-puts "SBAT entries: #{sbat.size}" if sbat
-
-# Access directory entries
-ole.root.each do |entry|
-  puts "#{entry.name}: starting_sector=#{entry.starting_sector}, size=#{entry.size}"
-end
-
-ole.close
-----
-
-== Performance Considerations
-
-OLE files can be large. For efficient reading:
-
-[source,ruby]
-----
-# Stream read large OLE files efficiently
-Omnizip::Ole.open('large.msi') do |ole|
-  # Only read streams you need
-  summary = ole.open_stream("\x05SummaryInformation")
-  if summary
-    # Read in chunks for large streams
-    chunk_size = 65536
-    while chunk = summary.read(chunk_size)
-      process(chunk)
-    end
-  end
-end
-----
-
 == See Also
 
 * link:seven-zip-format.html[7z Format] - Can contain OLE files

data/docs/guides/archive-formats/rar5.adoc

@@ -493,24 +493,24 @@ volumes.each { |v| puts "  - #{File.basename(v)}" }
 
 [source,ruby]
 ----
-# Convert ZIP to RAR5
-def zip_to_rar5(zip_file, rar_file)
-  zip = Omnizip::Formats::Zip::Reader.new(zip_file)
-
-  Omnizip::Formats::Rar::Rar5::Writer.new(rar_file,
-    compression: :lzma,
-    level: 5
-  ) do |writer|
-    zip.each_entry do |entry|
-      content = zip.read_entry(entry)
-      writer.add_data(entry.name, content)
-    end
+# Convert ZIP to RAR5 (extract first: the RAR5 writer adds files
+# from disk)
+def zip_to_rar5(zip_file, rar_file, workdir)
+  require "fileutils"
+
+  # Reader#read parses the central directory and returns self
+  zip = Omnizip::Formats::Zip::Reader.new(zip_file).read
+  zip.extract_all(workdir)
+
+  writer = Omnizip::Formats::Rar::Rar5::Writer.new(rar_file,
+                                                  compression: :store)
+  Dir.glob(File.join(workdir, "**", "*")).each do |path|
+    writer.add_file(path, path.delete_prefix("#{workdir}/")) if File.file?(path)
   end
-
-  zip.close
+  writer.write
 end
 
-zip_to_rar5('archive.zip', 'archive.rar')
+zip_to_rar5('archive.zip', 'archive.rar', 'workdir')
 ----
 
 === See Also

data/docs/guides/archive-formats/rpm-format.adoc

@@ -8,242 +8,101 @@ grand_parent: Guides
 [[rpm-format]]
 == Purpose
 
-RPM (Red Hat Package Manager) is the standard package format for Red Hat-based Linux distributions (RHEL, CentOS, Fedora). RPM packages contain software binaries, metadata, and scripts packaged in a single archive with a CPIO payload compressed using gzip, bzip2, xz, or zstd.
-
-== Key Characteristics
-
-[cols="1,3"]
-|===
-|Property |Value
-
-|Compression
-|gzip, bzip2, xz, or zstd
-
-|Encryption
-|GPG signature verification
-
-|Archive Support
-|Single package with CPIO payload
-
-|Large Files
-|Limited by CPIO and compression
-
-|Best For
-|Linux software distribution, RPM-based systems
-|===
+RPM is the package format of Red Hat-based Linux distributions. An
+RPM file is a lead, signature, metadata header and a payload — a
+CPIO archive compressed with gzip/bzip2/xz/zstd.
 
 == Basic Usage
 
-=== Read RPM Package Metadata
+=== Open a Package
 
 [source,ruby]
 ----
-# Open and read RPM metadata
-rpm = Omnizip::Rpm.open('package.rpm')
-
-puts "Name: #{rpm.name}"
-puts "Version: #{rpm.version}"
-puts "Release: #{rpm.release}"
-puts "Architecture: #{rpm.arch}"
-puts "Summary: #{rpm.summary}"
-puts "Description: #{rpm.description}"
-
-# List package contents
-rpm.each_entry do |entry|
-  puts "#{entry.path} (#{entry.size} bytes)"
+Omnizip::Formats::Rpm.open('package.rpm') do |rpm|
+  puts rpm.files.size
 end
 
+rpm = Omnizip::Formats::Rpm.open('package.rpm')
 rpm.close
 ----
 
-=== Extract RPM Package
+=== Package Metadata
 
 [source,ruby]
 ----
-# Extract all files from RPM
-Omnizip::Rpm.extract('package.rpm', '/output/directory/')
-
-# Extract specific files
-Omnizip::Rpm.open('package.rpm') do |rpm|
-  rpm.extract_files(['usr/bin/app', 'usr/share/man/man1/app.1.gz'], '/output/')
+info = Omnizip::Formats::Rpm.info('package.rpm')
+puts info[:name]        # => "app"
+puts info[:version]
+puts info[:release]
+puts info[:arch]
+puts info[:summary]
+puts info[:license]
+puts info[:vendor]
+puts info[:build_time]
+puts info[:file_count]
+
+# Same details on the reader
+Omnizip::Formats::Rpm.open('package.rpm') do |rpm|
+  puts rpm.name
+  puts rpm.version
+  puts rpm.license
 end
 ----
 
-=== Check RPM Signature
+=== List and Extract Files
 
 [source,ruby]
 ----
-# Verify RPM signature (requires GPG keys)
-rpm = Omnizip::Rpm.open('package.rpm')
-if rpm.signed?
-  puts "Package is GPG signed"
-  puts "Key ID: #{rpm.signature_key_id}"
+# File paths inside the payload
+Omnizip::Formats::Rpm.list('package.rpm')
+
+# Extract the payload (CPIO contents)
+Omnizip::Formats::Rpm.extract('package.rpm', '/output/directory/')
+
+# Or per-reader
+Omnizip::Formats::Rpm.open('package.rpm') do |rpm|
+  rpm.extract('/output/directory/')
 end
 ----
 
 == RPM Structure
 
-RPM packages consist of:
-
 . **Lead** - 96 bytes identifying the package
-. **Signature** - Header with cryptographic signatures
-. **Header** - Metadata (name, version, dependencies, scripts)
-. **Payload** - CPIO archive compressed with gzip/bzip2/xz/zstd
+. **Signature** - cryptographic signatures
+. **Header** - metadata (name, version, dependencies)
+. **Payload** - CPIO archive
 
 [source,ruby]
 ----
-# Internal RPM structure
-rpm = Omnizip::Rpm.open('package.rpm')
-
-# Access lead
+rpm = Omnizip::Formats::Rpm.open('package.rpm')
 puts rpm.lead.inspect
-
-# Access signature
 puts rpm.signature.inspect
-
-# Access header (metadata)
 puts rpm.header.inspect
-
-# Access payload directly (compressed CPIO)
-puts rpm.payload.inspect
 ----
 
-== Payload Extraction
-
-The RPM payload is a CPIO archive that can be extracted:
+== Payload
 
 [source,ruby]
 ----
-# Extract only the payload (files)
-Omnizip::Rpm.open('package.rpm') do |rpm|
-  rpm.extract_payload('/output/directory/')
-end
+Omnizip::Formats::Rpm.open('package.rpm') do |rpm|
+  puts "Compression: #{rpm.payload_compressor}"
 
-# Access payload entries directly
-Omnizip::Rpm.open('package.rpm') do |rpm|
-  rpm.each_payload_entry do |entry|
-    puts "Entry: #{entry.path}"
-    puts "Content: #{entry.read[0, 100]}..."
-  end
+  # Compressed CPIO bytes; decompress with the matching format
+  payload = rpm.payload
 end
 ----
 
-== Compression Types
-
-RPM supports four payload compression formats:
-
-[cols="2,1,1"]
-|===
-|Format |Extension |Compression Ratio
-
-|gzip
-|.gz
-|Good
-
-|bzip2
-|.bz2
-|Better
-
-|xz
-|.xz
-|Best
-
-|zstd
-|.zst
-|Best (modern)
-|===
-
-[source,ruby]
-----
-# Check compression type
-rpm = Omnizip::Rpm.open('package.rpm')
-puts "Compression: #{rpm.compression_type}"
-
-# Handle different compression types
-case rpm.compression_type
-when :gzip
-  puts "Using gzip decompression"
-when :bzip2
-  puts "Using bzip2 decompression"
-when :xz
-  puts "Using xz decompression"
-when :zstd
-  puts "Using zstd decompression"
-end
-----
-
-== Scriptlets
-
-RPM packages can contain pre/post install scripts:
-
-[source,ruby]
-----
-# Access scriptlets
-rpm = Omnizip::Rpm.open('package.rpm')
-
-puts "Pre-install script: #{rpm.pre_install_script}"
-puts "Post-install script: #{rpm.post_install_script}"
-puts "Pre-uninstall script: #{rpm.pre_uninstall_script}"
-puts "Post-uninstall script: #{rpm.post_uninstall_script}"
-----
-
 == Dependencies
 
-RPM packages declare dependencies:
-
-[source,ruby]
-----
-# Access dependencies
-rpm = Omnizip::Rpm.open('package.rpm')
-
-# Required packages
-puts "Requires:"
-rpm.requires.each do |dep|
-  puts "  #{dep.name} #{dep.version}"
-end
-
-# Provided capabilities
-puts "Provides:"
-rpm.provides.each do |cap|
-  puts "  #{cap.name}"
-end
-
-# Required capabilities
-puts "Requires:"
-rpm.requires.each do |req|
-  puts "  #{req.name} #{req.version}"
-end
-
-# Conflicts
-puts "Conflicts:"
-rpm.conflicts.each do |conf|
-  puts "  #{conf.name} #{conf.version}"
-end
-----
-
-== File Information
-
-RPM tracks detailed file information:
-
 [source,ruby]
 ----
-# Access file entries
-Omnizip::Rpm.open('package.rpm') do |rpm|
-  rpm.each_file do |file|
-    puts "Path: #{file.path}"
-    puts "Size: #{file.size}"
-    puts "Mode: #{file.mode.to_s(8)}"
-    puts "Owner: #{file.owner}"
-    puts "Group: #{file.group}"
-    puts "MD5: #{file.md5}" if file.md5
-    puts "Is config: #{file.config?}"
-    puts "Is doc: #{file.doc?}"
-  end
+Omnizip::Formats::Rpm.open('package.rpm') do |rpm|
+  rpm.requires.each { |name, op, version| puts "#{name} #{op} #{version}" }
+  rpm.provides.each { |name, op, version| puts "#{name} #{op} #{version}" }
+  rpm.conflicts.each { |name, op, version| puts "#{name} #{op} #{version}" }
 end
 ----
 
 == See Also
 
-* link:tar-format.html[TAR Format] - Related archive format
-* link:xz-format.html[XZ Format] - XZ compression used in some RPMs
-* link:cpio-format.html[CPIO Format] - Underlying payload format
+* link:gzip-format.html[GZIP Format] - Common payload compression