comicbook 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a990cb3f4650a5a8efb0de5f872f7242c6a3e9f7028f137022d003f92f401f4b
-  data.tar.gz: b10b662cfd46bbe3126b4c834b2e5c057a227d18bed5d0a97d4bc899af843192
+  metadata.gz: 8e9032e12765aa91a64364150391122a0324ee9f89b9987391f4708d1db7b0d6
+  data.tar.gz: de1dc67b4d78eb8ecf739b02381d78cf2a39518a6b12dd6bbef521dd77e1b8dd
 SHA512:
-  metadata.gz: 4d7e88350b4c8f9c111d68579509bdc90f8dbee09abf326a5255b9f2c4065255c1d6d863ff57df3cb42279565aee09ed67873bce779f3d734537b57c03745330
-  data.tar.gz: '0059293bd6b56943810b2fd5bb7ed730dfc1ad214371a5467e2ab73cd7fd8604b4ca66b822ca74051beb10187c15d193d589f58b6bfa02e7ed0d64d81cb3571c'
+  metadata.gz: 81a45ca97a476926a1d8216043069840e27f42c461175ebf0326cd0698e4cc0ea78f8627b3b932e23266ccc56081786eaec210cbbc07d1e5e452b11bcef94f4e
+  data.tar.gz: f073563d4dcc6253d140e6818f2c9e273dfdc8e6ce053a729b6cddddb115ef436d6afa80d3e4357cf2ff187112bb69f444032674a5a96db841a7df0664ff0f7e

data/.ruby-version

@@ -1 +1 @@
-3.4.7
+4.0.2

data/Brewfile

@@ -0,0 +1 @@
+brew 'vips'

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-14
+
+### Added
+
+- PDF to comic book conversion (PDF → .cb → .cbz/.cb7/.cbt) with configurable DPI (default 300)
+- PDF adapter with extract and pages support using libvips
+- `ruby-vips` gem dependency (lazy-loaded, only required for PDF features)
+- `ComicBook#info` method to read ComicInfo.xml metadata from archives and folders
+- `comicinfo` gem dependency for ComicInfo.xml parsing
+- `ComicBook::Info` alias for `ComicInfo::Issue`
+- `comicbook info` CLI subcommand with `--format` (verbose, terse, json, yaml), `--only`, and `--except` options
+- `--dpi` CLI option for PDF extraction
+- `--version`/`-v` CLI flag
+- Install `libvips-dev` in CI workflow
+
+## [0.2.0] - 2025-11-17
+
+### Added
+
+- CBR extraction support using vendored `unar`/`lsar` binaries
+- `--delete-original` CLI option for both extract and archive commands
+- `--images-only` CLI option for extract command
+- `images_only` option for Ruby API extraction
+- `delete_original` option for Ruby API extraction and archiving
+- CLI validation for unsupported archive output formats (CBR, CBA)
+
 ## [0.1.0] - 2025-10-26
 
+### Added
+
 - Initial release
+- CBZ support (extract and archive)
+- CB7 support (extract and archive)
+- CBT support (extract and archive)
+- CLI tool with `extract` and `archive` commands
+- Ruby API with `ComicBook.extract`, `ComicBook.new().archive`, and `ComicBook.new().pages`

data/README.md

@@ -7,14 +7,18 @@ A Ruby library and CLI tool for managing comic books archives.
 
 **`archive`** — to create a `.cb*` file (default: `.cbz`).
 
-Currently supported formats, `archive` and `extract`:
+**`info`** — to read ComicInfo.xml metadata from a `.cb*` file.
+
+Currently supported formats for `archive` and `extract`:
 - CB7 — [7zip](https://en.wikipedia.org/wiki/7-Zip)
 - CBT — [Tar](https://en.wikipedia.org/wiki/Tar_(computing))
 - CBZ — [Zip](https://en.wikipedia.org/wiki/ZIP_(file_format))
 
-Planned formats , only `extract`:
+Currently supported formats for `extract` only:
+- **CBR** — [RAR](https://en.wikipedia.org/wiki/WinRAR) is proprietary without an open source implementation license. Extracting support is provided using vendored [`unar`](https://theunarchiver.com/command-line) binaries because a large number of comic books are archived in .cbr/.rar format. No support for creating `.cbr` files will ever be added until RAR is open source (or reverse engineered).
+- **PDF** — Extract PDF pages as images using [libvips](https://www.libvips.org/). Requires libvips installed on the system.
 
-- **CBR** — [RAR](https://en.wikipedia.org/wiki/WinRAR) is proprietary without an open source implementation license. People use WinRAR (Windows-only) to create .rar files. Or `unrar` on Linux/macOS to open .rar files. Extracting support is provided because a large number of comic books are archived in .cbr/.rar format, primarily by Windows users. No support for creating `.cbr` files will ever be added until RAR is opensource (or reverse engineered).
+Planned formats for `extract` only:
 - **CBA** — [ACE](https://en.wikipedia.org/wiki/WinAce) is both proprietary and very old/outdated/unsupported. ACE extracting support is provided for historical posterity and completeness.
 
 ## Installation
@@ -33,21 +37,83 @@ gem install comicbook
 
 ## Usage
 
-In Ruby, you can use the `ComicBook` class to `extract` comic books archives from various formats. You `archive` a folder of images to create a comic book archive.
+### CLI
 
-### Extracting
+```sh
+# Extract a comic book archive
+comicbook extract path/to/archive.cbz
 
-```ruby
-ComicBook.extract 'path/to/archive.cbz'
+# Extract to a specific destination
+comicbook extract path/to/archive.cbz --to path/to/output
+
+# Extract only image files (exclude metadata like ComicInfo.xml)
+comicbook extract path/to/archive.cbz --images-only
+
+# Extract PDF at custom DPI (default: 300)
+comicbook extract path/to/comic.pdf --dpi 600
+
+# Create a comic book archive from a folder
+comicbook archive path/to/folder
+
+# Create archive at a specific destination
+comicbook archive path/to/folder --to path/to/output.cbz
+
+# Show ComicInfo.xml metadata
+comicbook info path/to/archive.cbz
+
+# Show info in different formats
+comicbook info path/to/archive.cbz --format json
+comicbook info path/to/archive.cbz --format yaml
+comicbook info path/to/archive.cbz --format terse
+
+# Show only specific fields
+comicbook info path/to/archive.cbz --only title,writer,publisher
+
+# Show all fields except specific ones
+comicbook info path/to/archive.cbz --except summary,review
+
+# Show help
+comicbook --help
 ```
-### Archiving
+
+### Ruby API
 
 ```ruby
-ComicBook.archive 'path/to/archive'
+# Extract a comic book archive (extracts all files by default)
+ComicBook.extract 'path/to/archive.cbz'
+
+# Extract to a specific destination
+ComicBook.extract 'path/to/archive.cbz', to: 'path/to/output'
+
+# Extract only image files (exclude metadata like ComicInfo.xml)
+ComicBook.extract 'path/to/archive.cbz', images_only: true
+
+# Create a comic book archive from a folder (creates .cbz by default)
+ComicBook.new('path/to/folder').archive
+
+# Create archive at a specific destination
+ComicBook.new('path/to/folder').archive to: 'path/to/output.cbz'
+
+# Get pages from an archive
+comic = ComicBook.new 'path/to/archive.cbz'
+comic.pages  # => [#<ComicBook::Page>, ...]
+
+# Read ComicInfo.xml metadata
+comic = ComicBook.new 'path/to/archive.cbz'
+comic.info        # => #<ComicInfo::Issue> or nil
+comic.info.title  # => "The Amazing Spider-Man"
+comic.info.writer # => "Dan Slott, Christos Gage"
 ```
 
 ## Development
 
+PDF support requires [libvips](https://www.libvips.org/). Install it with `brew bundle` (uses the included `Brewfile`) or manually:
+
+```sh
+brew install vips             # macOS
+sudo apt install libvips-dev  # Linux
+```
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Rakefile

@@ -5,4 +5,8 @@ require 'rubocop/rake_task'
 RSpec::Core::RakeTask.new :spec
 RuboCop::RakeTask.new
 
+desc 'Run tests and linter'
 task default: %i[spec rubocop]
+
+desc 'Alias of default: spec linter'
+task test: %i[spec rubocop]

data/SYSTEM.md

@@ -230,6 +230,6 @@ ComicBook::Error < StandardError
 The adapter pattern makes it easy to add new formats or extend existing ones without modifying core functionality.
 
 ## Version Information
-- **Current Version**: 0.1.0
-- **Ruby Requirement**: >= 3.4.7
+- **Current Version**: 0.2.0
+- **Ruby Requirement**: >= 4.0.0
 - **License**: MIT

data/lib/comic_book/adapter.rb

@@ -19,6 +19,10 @@ class ComicBook
       raise NotImplementedError, "#{self.class} must implement #pages"
     end
 
+    def info
+      raise NotImplementedError, "#{self.class} must implement #info"
+    end
+
     private
 
     attr_reader :path

data/lib/comic_book/cb/archiver.rb

@@ -0,0 +1,49 @@
+class ComicBook
+  class CB < Adapter
+    class Archiver
+      def initialize source_path
+        @source_path = File.expand_path source_path
+      end
+
+      def archive options = {}
+        output_path = options[:to] || determine_output_path
+
+        validate_destination! output_path
+
+        if File.directory? source_path
+          archive_folder output_path
+        else
+          archive_file output_path
+        end
+
+        output_path
+      end
+
+      private
+
+      attr_reader :source_path
+
+      def determine_output_path
+        base_name = File.basename source_path, '.*'
+        dir_name  = File.dirname  source_path
+
+        File.expand_path File.join(dir_name, "#{base_name}.cb")
+      end
+
+      def validate_destination! output_path
+        return unless File.exist? output_path
+
+        raise ComicBook::Error, "Destination already exists: #{output_path}"
+      end
+
+      def archive_folder output_path
+        FileUtils.mv source_path, output_path
+      end
+
+      def archive_file output_path
+        FileUtils.mkdir_p output_path
+        FileUtils.mv source_path, output_path
+      end
+    end
+  end
+end

data/lib/comic_book/cb/extractor.rb

@@ -0,0 +1,17 @@
+class ComicBook
+  class CB < Adapter
+    class Extractor
+      def initialize archive_path
+        @archive_path = File.expand_path archive_path
+      end
+
+      def extract
+        raise ComicBook::Error, '.cb folders are already extracted (they are uncompressed folders)'
+      end
+
+      private
+
+      attr_reader :archive_path
+    end
+  end
+end

data/lib/comic_book/cb.rb

@@ -0,0 +1,36 @@
+require 'comicinfo'
+require_relative 'adapter'
+require_relative 'cb/archiver'
+require_relative 'cb/extractor'
+
+class ComicBook
+  class CB < Adapter
+    def archive options = {}
+      Archiver.new(path).archive options
+    end
+
+    def info
+      xml_path = File.join path, 'ComicInfo.xml'
+      return nil unless File.exist? xml_path
+
+      ComicInfo.load xml_path
+    end
+
+    def extract _options = {}
+      Extractor.new(path).extract
+    end
+
+    def pages
+      pattern     = ComicBook::IMAGE_GLOB_PATTERN
+      search_path = File.join path, '**', pattern
+      image_files = Dir.glob search_path, File::FNM_CASEFOLD
+
+      image_files.sort.map do |file|
+        relative_path = Pathname.new(file).relative_path_from(Pathname.new(path)).to_s
+        basename      = File.basename file
+
+        ComicBook::Page.new relative_path, basename
+      end
+    end
+  end
+end

data/lib/comic_book/cb7/archiver.rb

@@ -10,7 +10,7 @@ class ComicBook
         delete_original = options.fetch :delete_original, false
 
         output_path = options[:to] || determine_output_path(extension)
-        create_7z_archive output_path
+        create_archive output_path
         cleanup_source_folder if delete_original
 
         output_path
@@ -27,11 +27,11 @@ class ComicBook
         File.expand_path File.join(dir_name, "#{base_name}.#{extension}")
       end
 
-      def create_7z_archive output_path
+      def create_archive output_path
         File.open(output_path, 'wb') do |file|
-          SevenZipRuby::Writer.open(file) do |szw|
+          SevenZipRuby::Writer.open(file) do |writer|
             find_image_files.each do |image_file|
-              add_file_to_7z szw, image_file
+              add_file writer, image_file
             end
           end
         end
@@ -42,12 +42,12 @@ class ComicBook
         Dir.glob(pattern, File::FNM_CASEFOLD).sort
       end
 
-      def add_file_to_7z szw, file
+      def add_file writer, file
         file_path     = Pathname.new file
         source_path   = Pathname.new source_folder
         relative_path = file_path.relative_path_from source_path
 
-        szw.add_file file, as: relative_path.to_s
+        writer.add_file file, as: relative_path.to_s
       end
 
       def cleanup_source_folder

data/lib/comic_book/cb7/extractor.rb

@@ -2,16 +2,17 @@ class ComicBook
   class CB7 < Adapter
     class Extractor
       def initialize archive_path
-        @archive_path = File.expand_path(archive_path)
+        @archive_path = File.expand_path archive_path
       end
 
       def extract options = {}
-        extension = options.fetch :extension, :cb
-        delete_original = options.fetch :delete_original, false
+        extension          = options.fetch :extension, :cb
+        delete_original    = options.fetch :delete_original, false
         destination_folder = options[:to]
 
         destination = destination_folder || determine_extract_path(extension)
-        extract_7z_contents destination
+        create_destination_directory destination
+        extract_contents destination, options
         cleanup_archive_file if delete_original
 
         destination
@@ -21,9 +22,13 @@ class ComicBook
 
       attr_reader :archive_path
 
+      def create_destination_directory destination
+        FileUtils.mkdir_p destination
+      end
+
       def determine_extract_path extension
         base_name    = File.basename archive_path, '.*'
-        dir_name     = File.dirname archive_path
+        dir_name     = File.dirname  archive_path
         archive_name = base_name
 
         archive_name << ".#{extension}" if extension
@@ -32,33 +37,43 @@ class ComicBook
         File.expand_path full_path
       end
 
-      def extract_7z_contents destination
+      def image_file? filename
+        ComicBook::IMAGE_EXTENSIONS.include? File.extname(filename.downcase)
+      end
+
+      def cleanup_archive_file
+        File.delete archive_path
+      end
+
+      def create_parent_directory file_path
+        parent_dir = File.dirname file_path
+        FileUtils.mkdir_p parent_dir
+      end
+
+      def extract_contents destination, options
         FileUtils.mkdir_p destination
 
         File.open(archive_path, 'rb') do |file|
-          SevenZipRuby::Reader.open(file) do |szr|
-            szr.entries.each do |entry|
-              next unless entry.file? && image_file?(entry.path)
-
-              extract_single_file entry, destination, szr
-            end
+          SevenZipRuby::Reader.open(file) do |seven_zip_reader|
+            extract_files destination, options, seven_zip_reader
           end
         end
       end
 
-      def extract_single_file entry, destination, szr
-        file_path = File.join(destination, entry.path)
-        FileUtils.mkdir_p File.dirname(file_path)
+      def extract_files destination, options, seven_zip_reader
+        seven_zip_reader.entries.each do |entry|
+          next unless entry.file?
+          next if options[:images_only] && !image_file?(entry.path)
 
-        File.binwrite(file_path, szr.extract_data(entry))
+          extract_single_file entry, destination, seven_zip_reader
+        end
       end
 
-      def cleanup_archive_file
-        File.delete archive_path
-      end
+      def extract_single_file entry, destination, seven_zip_reader
+        file_path = File.join destination, entry.path
+        create_parent_directory file_path
 
-      def image_file? filename
-        ComicBook::IMAGE_EXTENSIONS.include? File.extname(filename.downcase)
+        File.binwrite(file_path, seven_zip_reader.extract_data(entry))
       end
     end
   end

data/lib/comic_book/cb7.rb

@@ -1,4 +1,5 @@
 require 'seven_zip_ruby'
+require 'comicinfo'
 require_relative 'adapter'
 require_relative 'cb7/archiver'
 require_relative 'cb7/extractor'
@@ -13,34 +14,47 @@ class ComicBook
       Extractor.new(path).extract options
     end
 
-    def pages = collect_pages_from_7z
+    def info
+      xml = nil
 
-    private
+      File.open(path, 'rb') do |file|
+        SevenZipRuby::Reader.open(file) do |reader|
+          entry = reader.entries.find { it.path == 'ComicInfo.xml' }
+          xml   = reader.extract_data(entry.index) if entry
+        end
+      end
 
-    def collect_pages_from_7z
-      pages = []
+      return nil unless xml
 
-      File.open(path, 'rb') do |file|
-        SevenZipRuby::Reader.open(file) do |szr|
-          szr.entries.each do |entry|
-            next unless entry.file? && image_file?(entry.path)
+      ComicInfo.load xml
+    end
+
+    def pages
+      entries = []
 
-            pages << create_page_from_entry(entry)
+      File.open(path, 'rb') do |file|
+        SevenZipRuby::Reader.open(file) do |reader|
+          reader.entries.each do |entry|
+            entries << entry.path if entry.file?
           end
         end
       end
 
-      pages.sort_by(&:name)
+      entries.select { image_file? it }
+             .map    { create_page_from_entry it }
+             .sort_by(&:name)
     end
 
+    private
+
     def create_page_from_entry entry
-      basename = File.basename(entry.path)
+      basename = File.basename entry
 
-      ComicBook::Page.new entry.path, basename
+      ComicBook::Page.new entry, basename
     end
 
     def image_file? filename
-      extension = File.extname(filename.downcase)
+      extension = File.extname filename.downcase
 
       ComicBook::IMAGE_EXTENSIONS.include? extension
     end

data/lib/comic_book/cba.rb

@@ -0,0 +1,21 @@
+require_relative 'adapter'
+
+class ComicBook
+  class CBA < Adapter
+    def archive _options = {}
+      raise Error, 'CBA archiving not supported (ACE is proprietary)'
+    end
+
+    def extract _options = {}
+      raise Error, 'CBA extraction not yet implemented'
+    end
+
+    def info
+      raise Error, 'CBA info not yet implemented'
+    end
+
+    def pages
+      raise Error, 'CBA page listing not yet implemented'
+    end
+  end
+end

data/lib/comic_book/cbr/extractor.rb

@@ -0,0 +1,75 @@
+class ComicBook
+  class CBR < Adapter
+    class Extractor
+      def initialize archive_path
+        @archive_path = File.expand_path archive_path
+      end
+
+      def extract options = {}
+        extension          = options.fetch :extension, :cb
+        delete_original    = options.fetch :delete_original, false
+        destination_folder = options[:to]
+
+        destination = destination_folder || determine_extract_path(extension)
+        create_destination_directory destination
+        extract_contents destination, options
+        cleanup_archive_file if delete_original
+
+        destination
+      end
+
+      private
+
+      attr_reader :archive_path
+
+      def create_destination_directory destination
+        FileUtils.mkdir_p destination
+      end
+
+      def determine_extract_path extension
+        base_name    = File.basename archive_path, '.*'
+        dir_name     = File.dirname  archive_path
+        archive_name = base_name
+
+        archive_name << ".#{extension}" if extension
+
+        full_path = File.join dir_name, archive_name
+        File.expand_path full_path
+      end
+
+      def image_file? filename
+        ComicBook::IMAGE_EXTENSIONS.include? File.extname(filename.downcase)
+      end
+
+      def cleanup_archive_file
+        File.delete archive_path
+      end
+
+      def create_parent_directory file_path
+        parent_dir = File.dirname file_path
+        FileUtils.mkdir_p parent_dir
+      end
+
+      def extract_contents destination, options
+        FileUtils.mkdir_p destination
+        extract_files destination, options
+      end
+
+      def extract_files destination, options
+        CLIHelpers.unar_extract archive_path, destination
+        delete_non_images destination if options[:images_only]
+      end
+
+      def delete_non_images destination
+        archive_entries = CLIHelpers.lsar_list archive_path
+
+        archive_entries.each do |entry|
+          next if image_file? entry
+
+          file_path = File.join(destination, entry)
+          FileUtils.rm_f file_path
+        end
+      end
+    end
+  end
+end

data/lib/comic_book/cbr.rb

@@ -0,0 +1,50 @@
+require 'shellwords'
+require 'comicinfo'
+require_relative 'adapter'
+require_relative 'cbr/extractor'
+
+class ComicBook
+  class CBR < Adapter
+    def archive _options = {}
+      raise Error, 'CBR archiving not supported (RAR is proprietary)'
+    end
+
+    def extract options = {}
+      Extractor.new(path).extract options
+    end
+
+    def info
+      entries = CLIHelpers.lsar_list path
+      return nil unless entries.include? 'ComicInfo.xml'
+
+      Dir.mktmpdir do |temp_dir|
+        CLIHelpers.unar_extract path, temp_dir
+        xml_path = File.join temp_dir, 'ComicInfo.xml'
+        return nil unless File.exist? xml_path
+
+        ComicInfo.load xml_path
+      end
+    end
+
+    def pages
+      CLIHelpers.lsar_list(path)
+                .select { image_file? it }
+                .map    { create_page_from_entry it }
+                .sort_by(&:name)
+    end
+
+    private
+
+    def create_page_from_entry entry
+      basename = File.basename entry
+
+      ComicBook::Page.new entry, basename
+    end
+
+    def image_file? filename
+      extension = File.extname filename.downcase
+
+      ComicBook::IMAGE_EXTENSIONS.include? extension
+    end
+  end
+end