cbz_tools 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7fe3f88fb29727f7962453a2fee499507a67111de66b535e4306dd88a569c19
-  data.tar.gz: 5513eadeb2da736150f1423aff4d4b37ae7229946bcee1e1fbe599894c639295
+  metadata.gz: 34014f96dd63882bd66f0de3f3a3548faa507e279d37f335fc12ecf8cef3ab41
+  data.tar.gz: f54439b98ddad12995b30e74ca1d6e45f559acc5c7df0190af5610623e1911e1
 SHA512:
-  metadata.gz: c424857bf97688fb045f1e2f26b7740dd85fc6a8cd38e6cce6acad5c9d3f2a9900b510843b03dc292aaa4873dc68f45fb11ada59730c648988a8eb54d0c10841
-  data.tar.gz: b486e668e9106525f2053d8ac2e36f9271717ee524b934009f1f8f752eb3be007a1de09c281dc1afc36305382de81917d16e280b5dd94aa0d9644f48656252bc
+  metadata.gz: 37bc01a7b250c5382507314c57d6c3c208f122c8fd39802ce5308aec16baa07860530e120f37cb5ce69bbf5dcdcc0a145e7a3ce0ad81fc2276ba4ae0e461c835
+  data.tar.gz: 9b83a50b99751749896e4d395af34665d85004a49768b7d7b9dac9d578bf4d90fd58190e87c18415620ae3935def84893a61ed40c7dc93ccc682ca31cd819fd5

data/.vscode/settings.json

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

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [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`)
+
 ## [0.1.1] - 2026-08-03
 
 - Exclude development-only files from the packaged gem

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/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CbzTools
+  class Error < StandardError; end
+end

data/lib/cbz_tools/reader.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+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)
+    ensure
+      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?)
+        .map(&:name)
+        .select { |name| !name.include?("__macosx") && image?(name) }
+        .sort
+    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
+
+      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
+      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
+  end
+end

data/lib/cbz_tools/version.rb

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

data/lib/cbz_tools.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "cbz_tools/version"
-
-module CbzTools
-  class Error < StandardError; end
-  # Your code goes here...
-end
+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,14 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: cbz_tools
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - David Figueroa
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.'
@@ -18,10 +46,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".vscode/settings.json"
 - CHANGELOG.md
 - 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
 - sig/cbz_tools.rbs
 homepage: https://github.com/dmfigueroa/cbz_tools