comicbook 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a990cb3f4650a5a8efb0de5f872f7242c6a3e9f7028f137022d003f92f401f4b
-  data.tar.gz: b10b662cfd46bbe3126b4c834b2e5c057a227d18bed5d0a97d4bc899af843192
+  metadata.gz: a0e1f16bc54c8073078765c5edd09bf2e886ee042a859e6f6ec7c601876fc010
+  data.tar.gz: c7fbaa136dc9705ef955dd272c83a22864fc541200b9b435a34c850afedea34b
 SHA512:
-  metadata.gz: 4d7e88350b4c8f9c111d68579509bdc90f8dbee09abf326a5255b9f2c4065255c1d6d863ff57df3cb42279565aee09ed67873bce779f3d734537b57c03745330
-  data.tar.gz: '0059293bd6b56943810b2fd5bb7ed730dfc1ad214371a5467e2ab73cd7fd8604b4ca66b822ca74051beb10187c15d193d589f58b6bfa02e7ed0d64d81cb3571c'
+  metadata.gz: 3ad1f9e9e8d24c143e6dfb22a293e62d758ce6a865e19f7bf324e908e339f7557d303e873d0cc5448378e190214ce9e8c18bed3743480203fa708e9f313fb3a9
+  data.tar.gz: 8f7e8f708e4ff746e132d94a6a6fec8406196cabe246c2769ae1600684a2dfb7c2fe4d7dab32cd5f9c70e22967e35d942b2a649cc1784bea2734702c04036ac6

data/.ruby-version

@@ -1 +1 @@
-3.4.7
+4.0.0

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-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,15 @@ 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`:
+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).
 
-- **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,17 +34,49 @@ 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
+
+# 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 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>, ...]
 ```
 
 ## Development

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/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,28 @@
+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 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

@@ -13,34 +13,32 @@ class ComicBook
       Extractor.new(path).extract options
     end
 
-    def pages = collect_pages_from_7z
-
-    private
-
-    def collect_pages_from_7z
-      pages = []
+    def pages
+      entries = []
 
       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)
-
-            pages << create_page_from_entry(entry)
+        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,17 @@
+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 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,36 @@
+require 'shellwords'
+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 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

data/lib/comic_book/cbt/archiver.rb

@@ -6,14 +6,14 @@ class ComicBook
       end
 
       def archive options = {}
-        extension = options.fetch :extension, :cbt
-        destination = options[:to] || determine_output_path(extension)
+        extension       = options.fetch :extension, :cbt
         delete_original = options.fetch :delete_original, false
 
-        create_tar_file destination
+        output_path = options[:to] || determine_output_path(extension)
+        create_archive output_path
         cleanup_source_folder if delete_original
 
-        destination
+        output_path
       end
 
       private
@@ -27,43 +27,34 @@ class ComicBook
         File.expand_path File.join(dir_name, "#{base_name}.#{extension}")
       end
 
-      def create_tar_file destination
-        File.open(destination, 'wb') do |file|
-          Gem::Package::TarWriter.new(file) do |tar|
-            add_files_to_tar tar, source_folder
+      def create_archive output_path
+        File.open(output_path, 'wb') do |file|
+          Gem::Package::TarWriter.new(file) do |writer|
+            find_image_files.each do |image_file|
+              add_file writer, image_file
+            end
           end
         end
       end
 
-      def add_files_to_tar tar, folder, prefix = ''
-        Dir.entries(folder).sort.each do |entry|
-          next if ['.', '..'].include?(entry)
-
-          full_path = File.join(folder, entry)
-          tar_path = prefix.empty? ? entry : File.join(prefix, entry)
-
-          if File.directory?(full_path)
-            add_files_to_tar tar, full_path, tar_path
-          elsif image_file?(entry)
-            add_file_to_tar tar, full_path, tar_path
-          end
-        end
+      def find_image_files
+        pattern = File.join(source_folder, '**', ComicBook::IMAGE_GLOB_PATTERN)
+        Dir.glob(pattern, File::FNM_CASEFOLD).sort
       end
 
-      def add_file_to_tar tar, file_path, tar_path
-        stat = File.stat(file_path)
-        tar.add_file(tar_path, stat.mode) do |io|
-          File.open(file_path, 'rb') do |file|
-            io.write(file.read)
+      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
+
+        stat = File.stat file
+        writer.add_file(relative_path.to_s, stat.mode) do |io|
+          File.open(file, 'rb') do |f|
+            io.write f.read
           end
         end
       end
 
-      def image_file? filename
-        extension = File.extname(filename.downcase)
-        ComicBook::IMAGE_EXTENSIONS.include? extension
-      end
-
       def cleanup_source_folder
         FileUtils.rm_rf source_folder
       end