cbz_tools 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be6a34e670ac04d6ea7d87875e6ce57eb182dda4f6349f72404ae66ce6a863df
-  data.tar.gz: 46d9ff6e0b8b52d13027a1ea06558947e6407cc0408637acb9acf9cbe03aafe5
+  metadata.gz: 96ee68c0b79bcb1256324ad692bf441f0926443ab71e87db3715c0ca5c89cac0
+  data.tar.gz: 15d6235b0d040d8836a752da8e304bb89d2fd0976f9eb371f6f514b6dd8c97c4
 SHA512:
-  metadata.gz: 54063af8baff3b28a84f03d20339d85821f1d0326011faf81afecb4c5081840292a8083a936070d597040cc79ac4833d68c4717fb7a0d0575d68f2fceb823103
-  data.tar.gz: e264ef924c0781ef429da2aa89ee71dbc9ff7c3d37307bf832dd10e633852e1326af140ced09b2aaf8c4d5185deefd76e6dcf45b0b1f6e09a8989619c8dbc59f
+  metadata.gz: dfaee61a3965d6901835d58ca0206ee5bd5f4a05eb1ffb00d2248ca16755aeb1d418b54f3550fe9ef6d0d125aff393955aec459990a279259bc05d874e7d1adc
+  data.tar.gz: 7e2e12a38206a9a6ea43d49eb4474a60770d094c48d47746a3cb6f249496abf382af564caacd41e5426684077a23135018ef108795232c87e592a835740ef435

data/.vscode/settings.json

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

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [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.
+- **Breaking**: `Reader#comic_info` returns parsed hash (`{}` when absent), not raw XML.
+- Add `Reader#update_comic_info(metadata)` to write `ComicInfo.xml` back.
+- `Reader#read` is now private; use `first_image`, `image`, `comic_info`.
+
 ## [0.2.0] - 2026-08-03
 
 - Add `CbzTools::Reader` for reading CBZ archives (images and `ComicInfo.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/comic_info.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module CbzTools
+  # Reads and writes the ComicInfo.xml metadata embedded in CBZ archives.
+  #
+  # The two operations are symmetric over SCHEMA: every key on the left
+  # side of that hash is a field that {.parse} can read and {.build} can
+  # write. Extend the schema in place (for example, in an initializer)
+  # if you need to support custom fields.
+  module ComicInfo
+    class ParseError < Error
+    end
+
+    SCHEMA = {
+      title: "Title",
+      series: "Series",
+      series_sort: "SeriesSort",
+      localized_series: "LocalizedSeries",
+      number: "Number",
+      count: "Count",
+      volume: "Volume",
+      summary: "Summary",
+      notes: "Notes",
+      publisher: "Publisher",
+      imprint: "Imprint",
+      year: "Year",
+      month: "Month",
+      day: "Day",
+      writer: "Writer",
+      penciller: "Penciller",
+      inker: "Inker",
+      colorist: "Colorist",
+      letterer: "Letterer",
+      cover_artist: "CoverArtist",
+      editor: "Editor",
+      translator: "Translator",
+      genre: "Genre",
+      tags: "Tags",
+      web: "Web",
+      page_count: "PageCount",
+      language_iso: "LanguageISO",
+      format: "Format",
+      series_group: "SeriesGroup",
+      age_rating: "AgeRating",
+      community_rating: "CommunityRating",
+      black_and_white: "BlackAndWhite",
+      manga: "Manga",
+      characters: "Characters",
+      teams: "Teams",
+      locations: "Locations",
+      scan_information: "ScanInformation",
+      story_arc: "StoryArc",
+      gtin: "GTIN"
+    }
+
+    # Parses a ComicInfo.xml string into a symbol-keyed hash.
+    #
+    # Returns an empty hash when the input is empty, or when the XML is
+    # valid but has no <ComicInfo> root. Keys not in SCHEMA are ignored.
+    # Fields whose text is empty or whitespace-only are dropped.
+    #
+    # @param xml [String] the ComicInfo.xml document
+    # @return [Hash] parsed metadata, keyed by SCHEMA symbols
+    # @raise [ParseError] when the XML is malformed
+    def self.parse(xml)
+      doc = Nokogiri::XML(xml)
+      raise ParseError, "Malformed XML: #{doc.errors.first&.message}" if doc.errors.any?
+
+      root = doc.at("ComicInfo")
+      return {} unless root
+
+      SCHEMA.each_with_object({}) do |(key, tag), hash|
+        text = root.at(tag)&.text&.strip
+        hash[key] = text if text && !text.empty?
+      end
+    end
+
+    # Builds a ComicInfo.xml string from a metadata hash.
+    #
+    # Accepts symbol or string keys; non-SCHEMA keys are ignored. Values
+    # that are +nil+, empty, or whitespace-only are skipped so the
+    # resulting XML does not contain empty tags.
+    #
+    # @param metadata [Hash] field values keyed by SCHEMA symbols or strings
+    # @return [String] a ComicInfo.xml document
+    def self.build(metadata)
+      normalized = metadata.transform_keys(&:to_sym)
+      builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+        xml.ComicInfo(
+          "xmlns:xsd" => "http://www.w3.org/2001/XMLSchema",
+          "xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance"
+        ) do
+          SCHEMA.each do |key, tag|
+            value = normalized[key]
+            next if value.nil? || value.to_s.strip.empty?
+
+            xml.send(tag, value.to_s)
+          end
+        end
+      end
+      builder.to_xml
+    end
+  end
+end

data/lib/cbz_tools/reader.rb

@@ -2,12 +2,33 @@
 
 require "zip"
 
+require_relative "comic_info"
+
 module CbzTools
+  # Reads the contents of a CBZ (Comic Book ZIP) archive.
+  #
+  # The public surface is image access and parsed ComicInfo metadata;
+  # XML is an internal wire format and never appears on the API.
+  #
+  # @example Reading images and metadata
+  #   CbzTools::Reader.open("path/to/comic.cbz") do |reader|
+  #     reader.image_names.first    # => "page_001.jpg"
+  #     reader.first_image          # => "<image bytes>"
+  #     reader.comic_info           # => {title: "The Amazing Spider-Man", page_count: "32"}
+  #   end
   class Reader
+    # File extensions recognized as comic page images.
     IMAGE_EXTENSIONS = %w[.jpg .jpeg .png .webp].freeze
 
+    # Raised when {#image} is called with a name that does not match
+    # any entry in the archive.
     class ImageNotFoundError < Error; end
 
+    # Opens a CBZ archive, yields a reader, and closes it when the
+    # block exits — including on exception.
+    #
+    # @yieldparam reader [Reader] the open reader
+    # @return [void]
     def self.open(path, &block)
       reader = new(path)
       block.call(reader)
@@ -15,16 +36,26 @@ module CbzTools
       reader&.close
     end
 
+    # Opens the archive at the given path. Prefer {.open} unless you
+    # need to hold the reader open across multiple operations.
+    #
+    # @param path [String] path to a CBZ file
     def initialize(path)
       @path = path
       @zip = Zip::File.open(@path)
     end
 
+    # Releases the underlying zip handle. Safe to call more than once.
+    #
+    # @return [void]
     def close
       @zip&.close
       @zip = nil
     end
 
+    # Returns the names of all image entries in the archive, sorted.
+    #
+    # @return [Array<String>]
     def image_names
       @zip.entries
         .reject(&:directory?)
@@ -33,17 +64,19 @@ module CbzTools
         .sort
     end
 
-    def read(name)
-      entry = @zip.find_entry(name)
-      return nil unless entry
-
-      entry.get_input_stream.read
-    end
-
+    # Returns the bytes of the first image in the archive, or +nil+
+    # when there are no images.
+    #
+    # @return [String, nil]
     def first_image
       read(image_names.first)
     end
 
+    # Returns the bytes of a specific image by name.
+    #
+    # @param name [String] entry name within the archive
+    # @return [String]
+    # @raise [ImageNotFoundError] when no entry with that name exists
     def image(name)
       data = read(name)
       raise ImageNotFoundError, "Image '#{name}' not found in #{@path}" unless data
@@ -51,12 +84,43 @@ module CbzTools
       data
     end
 
+    # Returns the parsed ComicInfo metadata as a symbol-keyed hash.
+    #
+    # Returns an empty hash when the archive has no ComicInfo.xml.
+    # The lookup is case-insensitive (+comicinfo.xml+ is also
+    # recognized).
+    #
+    # @return [Hash] parsed metadata, keyed by SCHEMA symbols
+    # @raise [CbzTools::ComicInfo::ParseError] when ComicInfo.xml is malformed
     def comic_info
-      read("ComicInfo.xml") || read("comicinfo.xml")
+      xml = read("ComicInfo.xml") || read("comicinfo.xml")
+      xml ? CbzTools::ComicInfo.parse(xml) : {}
+    end
+
+    # Writes the given metadata hash back into the archive as
+    # ComicInfo.xml, replacing any existing entry with that name.
+    #
+    # Accepts symbol or string keys; non-SCHEMA keys are ignored.
+    #
+    # @param metadata [Hash] field values keyed by SCHEMA symbols or strings
+    # @return [void]
+    # @raise [Zip::Error] when the archive cannot be opened for writing
+    # @raise [SystemCallError] when an underlying I/O operation fails
+    def update_comic_info(metadata)
+      @zip.get_output_stream("ComicInfo.xml") do |f|
+        f.write(CbzTools::ComicInfo.build(metadata))
+      end
     end
 
     private
 
+    def read(name)
+      entry = @zip.find_entry(name)
+      return nil unless entry
+
+      entry.get_input_stream.read
+    end
+
     def image?(name)
       IMAGE_EXTENSIONS.any? { |ext| name.downcase.end_with?(ext) }
     end

data/lib/cbz_tools/version.rb

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

data/lib/cbz_tools.rb

@@ -3,3 +3,5 @@
 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

@@ -1,4 +1,85 @@
 module CbzTools
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  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]
+
+    class ImageNotFoundError < CbzTools::Error
+    end
+
+    def self.open: (String path) { (Reader reader) -> void } -> void
+
+    def initialize: (String path) -> void
+
+    def close: -> void
+
+    def image_names: -> Array[String]
+
+    def read: (String name) -> String?
+
+    def first_image: -> String?
+
+    def image: (String name) -> String
+
+    def comic_info: -> Hash[Symbol, String]
+
+    def update_comic_info: (Hash[Symbol | String, String] metadata) -> void
+
+    private
+
+    def read: (String name) -> String?
+
+    def image?: (String name) -> bool
+  end
+
+  module ComicInfo
+    SCHEMA: Hash[Symbol, String]
+
+    class ParseError < CbzTools::Error
+    end
+
+    def self.parse: (String xml) -> Hash[Symbol, String]
+
+    def self.build: (Hash[Symbol | String, String] metadata) -> String
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cbz_tools
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - David Figueroa
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
 description: 'Tools for working with CBZ comic book archives: reading and extracting
   their contents, reading and updating their embedded metadata, and converting CBR
   archives to CBZ.'
@@ -37,6 +51,8 @@ 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/version.rb