omnizip 0.3.37 → 0.3.38

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

data/docs/reference/api/overview.adoc

@@ -99,15 +99,16 @@ writer.close
 [source,ruby]
 ----
 # 7z archive
-writer = Omnizip::Formats::SevenZip::Writer.new('archive.7z')
-writer.add_file('document.txt')
-writer.add_directory('photos/')
-writer.close
+Omnizip::Formats::SevenZip.create('archive.7z') do |writer|
+  writer.add_file('document.txt')
+  writer.add_directory('photos/')
+end
 
 # ZIP archive
 writer = Omnizip::Formats::Zip::Writer.new('archive.zip')
 writer.add_file('document.txt')
-writer.close
+writer.add_directory('photos/')
+writer.write
 ----
 
 ==== Extracting Archives
@@ -115,26 +116,24 @@ writer.close
 [source,ruby]
 ----
 # 7z archive
-reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z')
-reader.extract_all('output/')
-reader.close
+Omnizip::Formats::SevenZip.open('archive.7z') do |reader|
+  reader.extract_all('output/')
+end
 
-# ZIP archive
-reader = Omnizip::Formats::Zip::Reader.new('archive.zip')
+# ZIP archive (call .read to parse before extracting)
+reader = Omnizip::Formats::Zip::Reader.new('archive.zip').read
 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"
+Omnizip::Formats::SevenZip.open('archive.7z') do |reader|
+  reader.list_files.each do |entry|
+    puts "#{entry.name}: #{entry.size} bytes"
+  end
 end
-reader.close
 ----
 
 === Error Handling
@@ -145,7 +144,7 @@ begin
   Omnizip.compress_file('input.txt', 'output.lzma')
 rescue Omnizip::CompressionError => e
   puts "Compression failed: #{e.message}"
-rescue Omnizip::AlgorithmNotFound => e
+rescue Omnizip::AlgorithmNotFoundError => e
   puts "Algorithm not found: #{e.message}"
 rescue IOError => e
   puts "I/O error: #{e.message}"

data/docs/troubleshooting/index.adoc

@@ -188,11 +188,8 @@ omnizip archive create archive.zip files/ \
 
 [source,ruby]
 ----
-# Try RAR4 reader
+# One reader covers both RAR4 and RAR5 (version auto-detected)
 reader = Omnizip::Formats::Rar::Reader.new('archive.rar')
-
-# Or RAR5 reader
-reader = Omnizip::Formats::Rar::Rar5::Reader.new('archive.rar')
 ----
 
 ### Getting Help

data/lib/omnizip/archive_handler.rb

@@ -71,6 +71,8 @@ module Omnizip
       tar: -> { Omnizip::ArchiveHandlers::TarHandler },
       seven_zip: -> { Omnizip::ArchiveHandlers::SevenZipHandler },
       rar: -> { Omnizip::ArchiveHandlers::RarHandler },
+      cpio: -> { Omnizip::ArchiveHandlers::CpioHandler },
+      iso: -> { Omnizip::ArchiveHandlers::IsoHandler },
     }.freeze
     private_constant :LAZY_LOAD_TRIGGERS
   end

data/lib/omnizip/archive_handlers/cpio_handler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Omnizip
+  module ArchiveHandlers
+    # Read-only adapter for the CPIO format (initramfs images, RPM
+    # payloads). Extraction and listing are supported; CPIO writing
+    # exists at the format level but is not exposed through the
+    # convenience archive API.
+    class CpioHandler
+      def create(_path, **_options)
+        raise Omnizip::UnsupportedFormatError,
+              "cpio archives cannot be created through the convenience " \
+              "API; use Omnizip::Formats::Cpio.create directly"
+      end
+
+      def extract_to(path, output_dir, **_)
+        Omnizip::Formats::Cpio.extract(path, output_dir)
+      end
+
+      def list(path, details: false, **_)
+        entries = Omnizip::Formats::Cpio.list(path)
+        if details
+          entries.map do |e|
+            { name: e.name, size: e.data.bytesize,
+              directory: e.name.end_with?("/"), mtime: nil }
+          end
+        else
+          entries.map(&:name)
+        end
+      end
+
+      def read_entry(path, entry_name, **_)
+        entry = Omnizip::Formats::Cpio.list(path)
+          .find { |e| e.name == entry_name }
+        unless entry
+          raise Errno::ENOENT, "Entry not found: #{entry_name}"
+        end
+
+        entry.data
+      end
+    end
+  end
+end
+
+Omnizip::ArchiveHandler.register(:cpio, Omnizip::ArchiveHandlers::CpioHandler.new)

data/lib/omnizip/archive_handlers/iso_handler.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Omnizip
+  module ArchiveHandlers
+    # Read-only adapter for the ISO 9660 format (disk images).
+    # Extraction and listing are supported; ISO writing exists at the
+    # format level but is not exposed through the convenience archive
+    # API.
+    class IsoHandler
+      def create(_path, **_options)
+        raise Omnizip::UnsupportedFormatError,
+              "iso images cannot be created through the convenience " \
+              "API; use Omnizip::Formats::Iso.create directly"
+      end
+
+      def extract_to(path, output_dir, **_)
+        Omnizip::Formats::Iso.extract(path, output_dir)
+      end
+
+      def list(path, details: false, **_)
+        entries = Omnizip::Formats::Iso.list(path)
+        if details
+          entries.map do |e|
+            { name: e.full_path, size: e.size, directory: e.directory?,
+              mtime: e.recording_date }
+          end
+        else
+          entries.map(&:full_path)
+        end
+      end
+
+      def read_entry(path, entry_name, **_)
+        entry = Omnizip::Formats::Iso.list(path)
+          .find { |e| e.full_path == entry_name }
+        unless entry
+          raise Errno::ENOENT, "Entry not found: #{entry_name}"
+        end
+        raise Errno::EISDIR, "Entry is a directory: #{entry_name}" if entry.directory?
+
+        Dir.mktmpdir("omnizip-iso-entry") do |dir|
+          dest = File.join(dir, "entry")
+          Omnizip::Formats::Iso.open(path) do |iso|
+            iso.extract_entry(entry_name, dest)
+          end
+          File.binread(dest)
+        end
+      end
+    end
+  end
+end
+
+Omnizip::ArchiveHandler.register(:iso, Omnizip::ArchiveHandlers::IsoHandler.new)

data/lib/omnizip/archive_handlers.rb

@@ -9,5 +9,7 @@ module Omnizip
     autoload :TarHandler, "omnizip/archive_handlers/tar_handler"
     autoload :SevenZipHandler, "omnizip/archive_handlers/seven_zip_handler"
     autoload :RarHandler, "omnizip/archive_handlers/rar_handler"
+    autoload :CpioHandler, "omnizip/archive_handlers/cpio_handler"
+    autoload :IsoHandler, "omnizip/archive_handlers/iso_handler"
   end
 end

data/lib/omnizip/cli.rb

@@ -25,6 +25,28 @@ module Omnizip
   # under Omnizip::Cli would re-trigger this file's autoload
   # mid-load.
   module Shared
+    # Thor 1.x does not treat --help/-h on subcommands as a request
+    # for help: the flag reaches the command as a positional argument
+    # and arity checking fails. Classes extending this module route
+    # those flags to the standard help output instead.
+    module HelpDispatch
+      def dispatch(meth, given_args, given_opts, config)
+        wants_help = [Array(given_args), Array(given_opts)].any? do |list|
+          list.include?("--help") || list.include?("-h")
+        end
+        if wants_help
+          name = meth || Array(given_args).grep_v(/\A-/).first
+          # Subcommand groups intercept their own --help (e.g.
+          # "archive create --help" must show the create usage).
+          return super if subcommands.include?(name)
+
+          return start(["help", name].compact, config)
+        end
+
+        super
+      end
+    end
+
     # Print a formatted error message and exit nonzero.
     #
     # @param error [StandardError] the error to display
@@ -51,6 +73,7 @@ module Omnizip
   # Profile commands subcommand group
   class ProfileCommands < Thor
     include Shared
+    extend Shared::HelpDispatch
 
     class << self
       def exit_on_failure?
@@ -99,6 +122,7 @@ module Omnizip
   # Archive commands subcommand group
   class ArchiveCommands < Thor
     include Shared
+    extend Shared::HelpDispatch
 
     class << self
       def exit_on_failure?
@@ -328,6 +352,7 @@ module Omnizip
   # files using various compression algorithms.
   class Cli < Thor
     include Shared
+    extend Shared::HelpDispatch
 
     class << self
       def exit_on_failure?

data/lib/omnizip/convenience.rb

@@ -230,16 +230,18 @@ module Omnizip
       ".7z" => :seven_zip,
     }.freeze
 
-    # Extensions naming real formats this gem can READ but not write
-    # through the convenience API. Writing them a ZIP under a foreign
-    # name was silent corruption; failing truthfully is the only
-    # honest behavior.
+    # Extensions naming formats with read-only convenience routing.
+    # Writing them a ZIP under a foreign name was silent corruption;
+    # creation raises truthfully instead (the format-level writers
+    # exist for RAR/CPIO/ISO but are not part of the archive API).
     READ_ONLY_FORMAT_EXTENSIONS = [".rar", ".iso", ".cpio"].freeze
 
     # Extensions whose format has a READ-ONLY handler: extraction and
     # listing route to it, while creation keeps raising.
     READ_ARCHIVE_FORMAT_EXTENSIONS = {
       ".rar" => :rar,
+      ".cpio" => :cpio,
+      ".iso" => :iso,
     }.freeze
 
     # Extension -> single-file decompressor (stream interface).

data/lib/omnizip/formats/iso/directory_builder.rb

@@ -43,6 +43,12 @@ module Omnizip
           # Allocate sectors for directories and files
           allocate_sectors(tree)
 
+          # Tree nodes are separate hashes from @files entries; copy
+          # the allocated file locations onto the tree so directory
+          # records reference the real extents (otherwise every
+          # record points at sector 0).
+          assign_file_locations(tree)
+
           # Build path table
           path_table = build_path_table(tree)
 
@@ -143,6 +149,24 @@ module Omnizip
           allocate_file_sectors
         end
 
+        # Copy allocated file locations onto the matching tree nodes
+        #
+        # @param tree [Hash] Directory tree root
+        def assign_file_locations(tree)
+          walk = lambda do |node|
+            (node[:children] || []).each do |child|
+              if child[:directory]
+                walk.call(child)
+              else
+                match = @files.find { |f| f[:iso_path] == child[:iso_path] }
+                child[:location] = match[:location] if match
+                child[:size] = match[:size] if match
+              end
+            end
+          end
+          walk.call(tree)
+        end
+
         # Allocate sectors for a directory
         #
         # @param dir_node [Hash] Directory node

data/lib/omnizip/formats/iso/reader.rb

@@ -90,8 +90,8 @@ module Omnizip
           @entries.each do |entry|
             next if entry.current_directory? || entry.parent_directory?
 
-            output_path = File.join(output_dir, entry.name)
-            extract_entry(entry.name, output_path)
+            output_path = File.join(output_dir, entry.full_path)
+            extract_entry(entry.full_path, output_path)
           end
         end
 

data/lib/omnizip/formats/iso/writer.rb

@@ -178,8 +178,13 @@ module Omnizip
             preparer: "OMNIZIP #{Omnizip::VERSION}",
             application: "OMNIZIP",
             level: 2,
-            rock_ridge: true,
-            joliet: true,
+            # Rock Ridge System Use fields and Joliet UCS-2 directory
+            # trees are not implemented; advertising either extension
+            # makes readers misparse the image (e.g. 7-Zip reads the
+            # ASCII names as UCS-2 via the cloned SVD), so both stay
+            # off until real implementations land.
+            rock_ridge: false,
+            joliet: false,
           }
         end
 
@@ -193,6 +198,7 @@ module Omnizip
             source: File.expand_path(dir_path),
             iso_path: iso_path,
             stat: File.stat(dir_path),
+            directory: true,
           }
 
           # Add all contents
@@ -219,6 +225,7 @@ module Omnizip
             source: File.expand_path(dir_path),
             iso_path: iso_path,
             stat: File.stat(dir_path),
+            directory: true,
           }
 
           Dir.foreach(dir_path) do |entry|
@@ -283,13 +290,22 @@ module Omnizip
         # @param builder [VolumeBuilder] Volume builder
         # @param dir_structure [Hash] Directory structure
         def write_volume_descriptors(io, builder, dir_structure)
+          # Fixed layout: 16 PVD, 17 terminator, 18 path table (L),
+          # 19 path table (BE), directory data from sector 22.
+          root = dir_structure[:root].merge(
+            total_sectors: dir_structure[:total_sectors],
+            path_table_size: dir_structure[:path_table_size],
+            path_table_location: 18,
+            path_table_location_be: 19,
+          )
+
           # Write primary volume descriptor
-          pvd = builder.build_primary(dir_structure[:root])
+          pvd = builder.build_primary(root)
           io.write(pvd)
 
           # Write Joliet supplementary descriptor if enabled
           if @joliet
-            svd = builder.build_joliet(dir_structure[:root])
+            svd = builder.build_joliet(root)
             io.write(svd)
           end
 

data/lib/omnizip/formats/iso.rb

@@ -69,7 +69,9 @@ module Omnizip
       # @param path [String] Path to ISO file
       # @return [Array<DirectoryRecord>] Directory entries
       def self.list(path)
-        open(path, &:entries)
+        entries = nil
+        open(path) { |iso| entries = iso.entries }
+        entries
       end
 
       # Extract ISO contents