cbz_tools 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34014f96dd63882bd66f0de3f3a3548faa507e279d37f335fc12ecf8cef3ab41
-  data.tar.gz: f54439b98ddad12995b30e74ca1d6e45f559acc5c7df0190af5610623e1911e1
+  metadata.gz: 30f58af31425d78057d97105cfe21164b6ec05263f0b86d2b2a0dca150792d5d
+  data.tar.gz: edd397b9588670cd49a3bcfe517f684ae9f684f4469a9725d1ac440f00da0fbe
 SHA512:
-  metadata.gz: 37bc01a7b250c5382507314c57d6c3c208f122c8fd39802ce5308aec16baa07860530e120f37cb5ce69bbf5dcdcc0a145e7a3ce0ad81fc2276ba4ae0e461c835
-  data.tar.gz: 9b83a50b99751749896e4d395af34665d85004a49768b7d7b9dac9d578bf4d90fd58190e87c18415620ae3935def84893a61ed40c7dc93ccc682ca31cd819fd5
+  metadata.gz: 57e09be8a89fec63e2cb22b140c6500afa29a0363a1f0e7b1b6d5ef75b9a137e4f6da4b1012031d18b2875db856e73145ded2fabf8532a6080d9f80d9ff98894
+  data.tar.gz: 73deffc4ac234b2288b2b8c5898cd12dc005561b79a7b5941cfb052ace8766fef6227bf935b6835226381f679d0bfb5fd2f9553fc68fd8cb2bc5ce309e7bfd45

data/.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-  "cSpell.words": ["comicinfo", "gtin", "penciller"]
+  "cSpell.words": ["comicinfo", "gtin", "penciller", "unrar"]
 }

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-04
+
+- `CbzTools::CbrConverter` now uses `unrar` directly — no extractor param required.
+- **Breaking**: Removed `extractor:` param, `ExtractionError`, and `extractor` attribute.
+- Runtime check raises `ArchiveError` if `unrar` is not in PATH.
+
+## [0.4.0] - 2026-08-03
+
+- Add `CbzTools::CbrConverter` for converting CBR archives to CBZ. The gem ships the orchestration (extract → repack → error model) but no default extractor — callers pass `extractor:` (anything responding to `call(cbr_path, destination_dir)` and raising `ExtractionError` on failure).
+
 ## [0.3.0] - 2026-08-03
 
 - Add `CbzTools::ComicInfo` (parse/build ComicInfo.xml, `SCHEMA`); raises `ParseError` on bad XML.

data/README.md

@@ -18,7 +18,37 @@ gem install cbz_tools
 
 ## Usage
 
-Usage documentation will be added as the features land.
+### Reading a CBZ archive
+
+```ruby
+CbzTools::Reader.open("path/to/comic.cbz") do |reader|
+  reader.image_names    # => ["page_001.jpg", "page_002.jpg", ...]
+  reader.first_image    # => "<image bytes>"
+  reader.comic_info     # => {title: "...", page_count: "32", ...}
+end
+```
+
+### Editing ComicInfo.xml inside a CBZ
+
+```ruby
+CbzTools::Reader.open("path/to/comic.cbz") do |reader|
+  reader.update_comic_info(title: "New Title", page_count: "32")
+end
+```
+
+### Converting CBR to CBZ
+
+`CbzTools::CbrConverter` converts CBR archives to CBZ using the `unrar`
+command-line tool (which must be installed on your system).
+
+```ruby
+CbzTools::CbrConverter.convert("path/to/comic.cbr", to: "path/to/comic.cbz")
+```
+
+Errors inherit from `CbzTools::Error`:
+
+- `CbzTools::CbrConverter::ArchiveError` — the destination couldn't be written,
+  `overwrite: false` and the destination already exists, or `unrar` is not installed.
 
 ## Development
 

data/lib/cbz_tools/cbr_converter.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "zip"
+require "pathname"
+require "open3"
+
+require_relative "system_dependencies"
+
+module CbzTools
+  # Converts a CBR (Comic Book RAR) archive into a CBZ (Comic Book ZIP)
+  # archive.
+  #
+  # Extraction is handled internally using the +unrar+ command-line tool,
+  # which must be installed on the system. Consumers do not need to
+  # install or configure any extraction backend.
+  #
+  # @example Single-shot conversion
+  #   CbzTools::CbrConverter.convert("path/to/comic.cbr", to: "path/to/comic.cbz")
+  #
+  # @example Reusing one converter across many conversions
+  #   converter = CbzTools::CbrConverter.new
+  #   paths.each { |p| converter.convert(p, to: p.sub(/\.cbr\z/i, ".cbz")) }
+  class CbrConverter
+    class ArchiveError < Error
+    end
+
+    # @see #convert
+    #
+    # @param cbr_path [String] source CBR path
+    # @param to [String] destination CBZ path
+    # @param overwrite [Boolean] when false, raise {ArchiveError} if
+    #   +to+ already exists; default true
+    # @param work_in [String, nil] work directory; when nil (default),
+    #   a fresh +Dir.mktmpdir+ is created and cleaned up. When set, the
+    #   converter uses that directory and leaves cleanup to the caller
+    #   (useful when batching many conversions).
+    # @return [String] the destination CBZ path
+    # @raise [ArchiveError] when target cannot be written or unrar is unavailable
+    def self.convert(cbr_path, to:, overwrite: true, work_in: nil)
+      new.convert(cbr_path, to: to, overwrite: overwrite, work_in: work_in)
+    end
+
+    def convert(cbr_path, to:, overwrite: true, work_in: nil)
+      ensure_target_slot!(to, overwrite: overwrite)
+      File.delete(to) if overwrite && File.exist?(to)
+
+      in_workdir(work_in) do |temp_dir|
+        extract(cbr_path, temp_dir)
+        repack(temp_dir, to)
+      end
+
+      to
+    end
+
+    private
+
+    def extract(cbr_path, destination)
+      unrar = SystemDependencies.unrar!
+      _, stderr, status = Open3.capture3(unrar, "x", "-o+", cbr_path, "#{destination}/")
+
+      unless status.success?
+        raise ArchiveError, "unrar failed: #{stderr}"
+      end
+    rescue SystemDependencies::MissingExecutableError => e
+      raise ArchiveError, e.message
+    rescue => e
+      raise ArchiveError, "Failed to extract CBR: #{e.message}"
+    end
+
+    def ensure_target_slot!(to, overwrite:)
+      return if overwrite || !File.exist?(to)
+
+      raise ArchiveError, "Target #{to} already exists (pass overwrite: true to replace)"
+    end
+
+    def in_workdir(work_in, &block)
+      if work_in
+        FileUtils.mkdir_p(work_in)
+        yield work_in
+      else
+        Dir.mktmpdir(&block)
+      end
+    end
+
+    def repack(source_dir, target_path)
+      Zip::File.open(target_path, create: true) do |zipfile|
+        each_file_in(source_dir) { |file| add_to_zip(zipfile, source_dir, file) }
+      end
+    rescue Zip::Error, SystemCallError => e
+      raise ArchiveError, "Failed to write CBZ #{target_path}: #{e.class}: #{e.message}"
+    end
+
+    def each_file_in(source_dir)
+      Dir["#{source_dir}/**/*"].each do |path|
+        yield path unless File.directory?(path)
+      end
+    end
+
+    def add_to_zip(zipfile, source_dir, file_path)
+      relative = Pathname.new(file_path).relative_path_from(Pathname.new(source_dir)).to_s
+      zipfile.add(relative, file_path)
+    end
+  end
+end

data/lib/cbz_tools/system_dependencies.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CbzTools
+  module SystemDependencies
+    class MissingExecutableError < StandardError; end
+
+    def self.find_executable(name)
+      extensions = Gem.win_platform? ? ENV.fetch("PATHEXT", "").split(";") : [""]
+
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |directory|
+        extensions.each do |extension|
+          path = File.join(directory, "#{name}#{extension}")
+          return path if File.file?(path) && File.executable?(path)
+        end
+      end
+
+      nil
+    end
+
+    def self.unrar!
+      find_executable("unrar") ||
+        raise(
+          MissingExecutableError,
+          "`unrar` is required for CBR conversion but was not found in PATH. " \
+          "Install unrar using your system's package manager."
+        )
+    end
+  end
+end

data/lib/cbz_tools/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CbzTools
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/cbz_tools.rb

@@ -4,3 +4,4 @@ require_relative "cbz_tools/version"
 require_relative "cbz_tools/error"
 require_relative "cbz_tools/reader"
 require_relative "cbz_tools/comic_info"
+require_relative "cbz_tools/cbr_converter"

data/sig/cbz_tools.rbs

@@ -4,6 +4,43 @@ module CbzTools
   class Error < StandardError
   end
 
+  class CbrConverter
+    class ExtractionError < CbzTools::Error
+    end
+
+    class ArchiveError < CbzTools::Error
+    end
+
+    attr_reader extractor: untyped
+
+    def self.convert: (
+      String cbr_path,
+      to: String,
+      ?overwrite: bool,
+      ?work_in: String?,
+      ?extractor: untyped
+    ) -> String
+
+    def initialize: (?extractor: untyped) -> void
+
+    def convert: (
+      String cbr_path,
+      to: String,
+      ?overwrite: bool,
+      ?work_in: String?
+    ) -> String
+
+    private
+
+    def ensure_extractor!: -> void
+
+    def ensure_target_slot!: (String to, overwrite: bool) -> void
+
+    def in_workdir: (String? work_in) { (String) -> void } -> void
+
+    def repack: (String source_dir, String target_path) -> void
+  end
+
   class Reader
     IMAGE_EXTENSIONS: Array[String]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cbz_tools
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - David Figueroa
@@ -51,9 +51,11 @@ files:
 - LICENSE.txt
 - README.md
 - lib/cbz_tools.rb
+- lib/cbz_tools/cbr_converter.rb
 - lib/cbz_tools/comic_info.rb
 - lib/cbz_tools/error.rb
 - lib/cbz_tools/reader.rb
+- lib/cbz_tools/system_dependencies.rb
 - lib/cbz_tools/version.rb
 - sig/cbz_tools.rbs
 homepage: https://github.com/dmfigueroa/cbz_tools
@@ -77,7 +79,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-requirements: []
+requirements:
+- unrar executable available in PATH (for CBR conversion)
 rubygems_version: 4.0.17
 specification_version: 4
 summary: Read, extract, and edit metadata of CBZ comic archives, and convert CBR to