cbz_tools 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34014f96dd63882bd66f0de3f3a3548faa507e279d37f335fc12ecf8cef3ab41
-  data.tar.gz: f54439b98ddad12995b30e74ca1d6e45f559acc5c7df0190af5610623e1911e1
+  metadata.gz: 96ee68c0b79bcb1256324ad692bf441f0926443ab71e87db3715c0ca5c89cac0
+  data.tar.gz: 15d6235b0d040d8836a752da8e304bb89d2fd0976f9eb371f6f514b6dd8c97c4
 SHA512:
-  metadata.gz: 37bc01a7b250c5382507314c57d6c3c208f122c8fd39802ce5308aec16baa07860530e120f37cb5ce69bbf5dcdcc0a145e7a3ce0ad81fc2276ba4ae0e461c835
-  data.tar.gz: 9b83a50b99751749896e4d395af34665d85004a49768b7d7b9dac9d578bf4d90fd58190e87c18415620ae3935def84893a61ed40c7dc93ccc682ca31cd819fd5
+  metadata.gz: dfaee61a3965d6901835d58ca0206ee5bd5f4a05eb1ffb00d2248ca16755aeb1d418b54f3550fe9ef6d0d125aff393955aec459990a279259bc05d874e7d1adc
+  data.tar.gz: 7e2e12a38206a9a6ea43d49eb4474a60770d094c48d47746a3cb6f249496abf382af564caacd41e5426684077a23135018ef108795232c87e592a835740ef435

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [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,57 @@ 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` orchestrates the extract → repack → CBZ step,
+but it does **not** ship an extractor. Pass anything responding to
+`call(cbr_path, destination_dir)` (and that raises `ExtractionError`
+on failure):
+
+```ruby
+extractor = MyApp::UnrarExtractor.new
+CbzTools::CbrConverter.convert("path/to/comic.cbr",
+  to: "path/to/comic.cbz",
+  extractor: extractor)
+```
+
+Reuse one extractor across many conversions with `work_in:` to pool
+the tmpdir:
+
+```ruby
+extractor = MyApp::UnrarExtractor.new
+work_in   = Dir.mktmpdir("batch")
+converter = CbzTools::CbrConverter.new(extractor: extractor)
+
+paths.each do |cbr|
+  converter.convert(cbr, to: cbr.sub(/\.cbr\z/i, ".cbz"), work_in: work_in)
+end
+```
+
+Errors inherit from `CbzTools::Error`:
+
+- `CbzTools::CbrConverter::ExtractionError` — the extractor failed.
+- `CbzTools::CbrConverter::ArchiveError` — no extractor supplied,
+  the destination couldn't be written, or `overwrite: false` and the
+  destination already exists.
 
 ## Development
 

data/lib/cbz_tools/cbr_converter.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "zip"
+require "pathname"
+
+module CbzTools
+  # Converts a CBR (Comic Book RAR) archive into a CBZ (Comic Book ZIP)
+  # archive.
+  #
+  # The CBR extraction step is delegated to an injectable +extractor+
+  # — anything that responds to +call(cbr_path, destination_dir)+ and
+  #   raises {CbzTools::CbrConverter::ExtractionError} on failure. Callers (not this gem) own the
+  # extractor; this class is deliberately agnostic about which binary,
+  # library, or pure-Ruby implementation is used to expand the source.
+  #
+  # @example Single-shot conversion with an explicit extractor
+  #   extractor = MyApp::UnrarExtractor.new
+  #   CbzTools::CbrConverter.convert("path/to/comic.cbr",
+  #     to: "path/to/comic.cbz",
+  #     extractor: extractor)
+  #
+  # @example Reusing one extractor across many conversions
+  #   extractor = MyApp::UnrarExtractor.new
+  #   converter = CbzTools::CbrConverter.new(extractor: extractor)
+  #   paths.each { |p| converter.convert(p, to: p.sub(/\.cbr\z/i, ".cbz")) }
+  class CbrConverter
+    # Raised when the underlying extractor fails to expand the source
+    # CBR into a directory. Propagated untouched so callers can rescue
+    # it without unwrapping.
+    class ExtractionError < Error
+    end
+
+    # Raised when the resulting CBZ cannot be written, when the
+    # destination already exists and +overwrite:+ is false, or when no
+    # +extractor:+ was supplied. Propagated untouched from the
+    # relevant step.
+    class ArchiveError < Error
+    end
+
+    # @return [#call, nil] the configured extractor, or +nil+ if none
+    #   was supplied. Read-only; there is no corresponding writer.
+    attr_reader :extractor
+
+    # @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).
+    # @param extractor [#call] extractor backend; required.
+    # @return [String] the destination CBZ path
+    # @raise [ArchiveError] when +extractor:+ is missing or target cannot be written
+    # @raise [ExtractionError] when the extractor fails
+    def self.convert(cbr_path, to:, overwrite: true, work_in: nil, extractor: nil)
+      new(extractor: extractor).convert(cbr_path, to: to, overwrite: overwrite, work_in: work_in)
+    end
+
+    # @param extractor [#call, nil] anything responding to
+    #   +call(cbr_path, destination_dir)+ that raises {ExtractionError}
+    #   on failure. Required — {#convert} raises {ArchiveError} if left
+    #   as +nil+.
+    def initialize(extractor: nil)
+      @extractor = extractor
+    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] see {.convert}
+    # @return [String] the destination CBZ path
+    # @raise [ArchiveError] when no extractor was configured or target cannot be written
+    # @raise [ExtractionError] when the extractor fails
+    def convert(cbr_path, to:, overwrite: true, work_in: nil)
+      ensure_extractor!
+      ensure_target_slot!(to, overwrite: overwrite)
+      File.delete(to) if overwrite && File.exist?(to)
+
+      in_workdir(work_in) do |temp_dir|
+        @extractor.call(cbr_path, temp_dir)
+        repack(temp_dir, to)
+      end
+
+      to
+    end
+
+    private
+
+    def ensure_extractor!
+      raise ArchiveError,
+        "No extractor configured; pass `extractor:` to CbrConverter.convert or CbrConverter.new" unless @extractor
+    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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CbzTools
-  VERSION = "0.3.0"
+  VERSION = "0.4.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.4.0
 platform: ruby
 authors:
 - David Figueroa
@@ -51,6 +51,7 @@ 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