cbz_tools 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be6a34e670ac04d6ea7d87875e6ce57eb182dda4f6349f72404ae66ce6a863df
-  data.tar.gz: 46d9ff6e0b8b52d13027a1ea06558947e6407cc0408637acb9acf9cbe03aafe5
+  metadata.gz: 34014f96dd63882bd66f0de3f3a3548faa507e279d37f335fc12ecf8cef3ab41
+  data.tar.gz: f54439b98ddad12995b30e74ca1d6e45f559acc5c7df0190af5610623e1911e1
 SHA512:
-  metadata.gz: 54063af8baff3b28a84f03d20339d85821f1d0326011faf81afecb4c5081840292a8083a936070d597040cc79ac4833d68c4717fb7a0d0575d68f2fceb823103
-  data.tar.gz: e264ef924c0781ef429da2aa89ee71dbc9ff7c3d37307bf832dd10e633852e1326af140ced09b2aaf8c4d5185deefd76e6dcf45b0b1f6e09a8989619c8dbc59f
+  metadata.gz: 37bc01a7b250c5382507314c57d6c3c208f122c8fd39802ce5308aec16baa07860530e120f37cb5ce69bbf5dcdcc0a145e7a3ce0ad81fc2276ba4ae0e461c835
+  data.tar.gz: 9b83a50b99751749896e4d395af34665d85004a49768b7d7b9dac9d578bf4d90fd58190e87c18415620ae3935def84893a61ed40c7dc93ccc682ca31cd819fd5

data/.vscode/settings.json

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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/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.3.0"
 end

data/lib/cbz_tools.rb

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

data/sig/cbz_tools.rbs

@@ -1,4 +1,48 @@
 module CbzTools
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  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.3.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,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/cbz_tools.rb
+- lib/cbz_tools/comic_info.rb
 - lib/cbz_tools/error.rb
 - lib/cbz_tools/reader.rb
 - lib/cbz_tools/version.rb