epub_tools 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 815d8970acc779f70f7d86395a3658a296536675539dfcf3e7f9a0e0f2d4153a
-  data.tar.gz: da9131f5868b8e8c438e9f41c526d62a2d9f70a320e8d20fa14ffcf4a487f22c
+  metadata.gz: 3920ca32a1d5595866904c273c561dceec0021c259708317938e6ee6825adb3f
+  data.tar.gz: '0490275853356243b7b9ba25367439e6cb2fbee44ac43c71984a9b91f06e2464'
 SHA512:
-  metadata.gz: a7dc1015fc79f4c72edec8fb672622122a3540ef3b8923683777a178d397fff5af4e0b0765f237e748ca7a103b9e4c2c0c0c0902d180fcd9cb87e90c613c862f
-  data.tar.gz: fe60fa02c6a7db816b7aab2f5fe368de1a463fdaaa5aa1892146281362ea2cda49d904da541b67e34b2329225e01d9fcc7cd9a3a4c15503cb06cf3d6a10e26ec
+  metadata.gz: 1c0dfa04ad854e968f2e0ecb1ef3572f598269fedd91278602e0dd3bf524efc2358bab95b800966df175add2b9357ca4d0de366b4d21b30400d599946d299a72
+  data.tar.gz: df4bfb3cc82a0271ec320d523d41fcb8f36dd2b93d39419d5b719ea1bd24bf089163d80cd408dd6da16482e374567baf003e1e06e2eeee24cff844fcbbf06eaf

data/.gitignore

@@ -7,3 +7,5 @@ vendor/bundle/
 *.gem
 
 text_style_classes.yaml
+
+**/.claude/

data/.rubocop.yml

@@ -0,0 +1,41 @@
+# The behavior of RuboCop can be controlled via the .rubocop.yml
+# configuration file. It makes it possible to enable/disable
+# certain cops (checks) and to alter their behavior if they accept
+# any parameters. The file can be placed either in your home
+# directory or in some project directory.
+#
+# RuboCop will start looking for the configuration file in the directory
+# where the inspected file is and continue its way up to the root directory.
+#
+# See https://docs.rubocop.org/rubocop/configuration
+
+AllCops:
+  NewCops: enable
+
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Minitest/MultipleAssertions:
+  Enabled: false

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.5

data/Gemfile

@@ -2,18 +2,22 @@
 
 ruby '>= 3.2'
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
-gem "nokogiri", "~> 1.18"
-gem "rake", "~> 13.2"
-gem "rubyzip", "~> 2.4"
+gem 'nokogiri', '~> 1.18'
+gem 'rake', '~> 13.2'
+gem 'rubyzip', '~> 2.4'
 
-group :test do
-  gem "minitest", "~> 5.25"
-  gem "simplecov", require: false
+group :test, :development do
+  gem 'minitest', '~> 5.25'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-minitest', '~> 0.38.0', require: false
+  gem 'rubocop-rake', '~> 0.7.1', require: false
+  gem 'simplecov', require: false
 end
 
 group :doc do
-  gem "yard", "~> 0.9.37"
+  gem 'rdoc', '~> 6.13'
+  gem 'webrick', '~> 1.9'
+  gem 'yard', '~> 0.9.37'
 end
-

data/Gemfile.lock

@@ -1,33 +1,79 @@
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.3)
+    date (3.4.1)
     docile (1.4.1)
+    erb (5.0.2)
+    json (2.13.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
     minitest (5.25.5)
-    nokogiri (1.18.8-aarch64-linux-gnu)
+    nokogiri (1.18.9-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-aarch64-linux-musl)
+    nokogiri (1.18.9-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-gnu)
+    nokogiri (1.18.9-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm-linux-musl)
+    nokogiri (1.18.9-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.8-arm64-darwin)
+    nokogiri (1.18.9-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-darwin)
+    nokogiri (1.18.9-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-gnu)
+    nokogiri (1.18.9-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.8-x86_64-linux-musl)
+    nokogiri (1.18.9-x86_64-linux-musl)
       racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    psych (5.2.6)
+      date
+      stringio
     racc (1.8.1)
-    rake (13.2.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
+    regexp_parser (2.11.2)
+    rubocop (1.79.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.46.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-minitest (0.38.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    ruby-progressbar (1.13.0)
     rubyzip (2.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    stringio (3.1.7)
+    unicode-display_width (3.1.5)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    webrick (1.9.1)
     yard (0.9.37)
 
 PLATFORMS
@@ -44,12 +90,17 @@ DEPENDENCIES
   minitest (~> 5.25)
   nokogiri (~> 1.18)
   rake (~> 13.2)
+  rdoc (~> 6.13)
+  rubocop (~> 1.75)
+  rubocop-minitest (~> 0.38.0)
+  rubocop-rake (~> 0.7.1)
   rubyzip (~> 2.4)
   simplecov
+  webrick (~> 1.9)
   yard (~> 0.9.37)
 
 RUBY VERSION
-   ruby 3.4.3p32
+   ruby 3.4.5p51
 
 BUNDLED WITH
-   2.6.7
+   2.7.0

data/README.md

@@ -1,16 +1,20 @@
  # EPUB Tools
 
-[![Build Status](https://github.com/jaimerodas/epub_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimerodas/epub_tools/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Build Status](https://github.com/jaimerodas/epub_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimerodas/epub_tools/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Gem Version](https://badge.fury.io/rb/epub_tools.svg)](https://badge.fury.io/rb/epub_tools)
 
 **TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, and unpack EPUB books.
 
 ## Installation
-Install the gem via RubyGems:
+
+### Requirements
+- Ruby 3.2 or higher
+
+### Install from RubyGems
 ```bash
 gem install epub_tools
 ```
 
-Or build and install locally:
+### Build and install locally
 ```bash
 bundle install
 gem build epub_tools.gemspec
@@ -101,7 +105,7 @@ EpubTools::UnpackEbook.new('MyBook.epub', 'unpacked_dir').run
 ## Development & Testing
 Clone the repo and install dependencies:
 ```bash
-git clone <repo-url>
+git clone https://github.com/jaimerodas/epub_tools.git
 cd epub_tools
 bundle install
 ```
@@ -111,9 +115,25 @@ Run tests:
 bundle exec rake test
 ```
 
-Enable coverage reporting:
+Run linting (RuboCop):
+```bash
+bundle exec rubocop
+```
+## Documentation
+
+Detailed API documentation can be generated using YARD. To view the docs locally, serve the documentation locally with YARD:
+
+```bash
+bundle exec yard server --reload
+```
+
+Then navigate to http://localhost:8808 in your browser.
+
+To (re)generate the documentation, install the documentation dependencies and run:
+
 ```bash
-COVERAGE=true bundle exec rake test
+bundle install --with doc
+bundle exec yard doc
 ```
 
 ## Contributing

data/bin/epub-tools

@@ -1,112 +1,6 @@
 #!/usr/bin/env ruby
 require_relative '../lib/epub_tools'
 
-prog = File.basename($PROGRAM_NAME)
-# Global version flag: print version and exit if invoked as `epub-tools -v/--version`
-if ARGV[0] == '-v' || ARGV[0] == '--version'
-  puts EpubTools::VERSION
-  exit 0
-end
-script_dir = File.expand_path(File.join(__dir__, '..'))
-commands = %w[add extract init split pack unpack compile]
-
-if ARGV.empty? || !commands.include?(ARGV[0])
-  puts <<~USAGE
-    Usage: #{prog} COMMAND [options]
-    Commands:
-      init      Initialize a bare-bones EPUB
-      extract   Extract XHTML files from EPUBs
-      split     Split XHTML into separate XHTMLs per chapter
-      add       Add chapter XHTML files into an EPUB
-      pack      Package an EPUB directory into a .epub file
-      unpack    Unpack an EPUB file into a directory
-      compile   Takes EPUBs in a dir and splits, cleans, and compiles into a single EPUB.
-  USAGE
-  exit 1
-end
-
-cmd = ARGV.shift
-
-case cmd
-when 'add'
-options = {}
-EpubTools::CLIHelper.parse(options, [:chapters_dir, :epub_oebps_dir]) do |opts, o|
-  opts.banner = "Usage: #{prog} add [options]"
-  opts.on('-c DIR', '--chapters-dir DIR', 'Chapters directory (required)') { |v| o[:chapters_dir] = v }
-  opts.on('-e DIR', '--epub-oebps-dir DIR', 'EPUB OEBPS directory (required)') { |v| o[:epub_oebps_dir] = v }
-end
-
-EpubTools::AddChapters.new(options[:chapters_dir], options[:epub_oebps_dir]).run
-
-when 'extract'
-  options = { verbose: true }
-  EpubTools::CLIHelper.parse(options, [:source_dir, :target_dir]) do |opts, o|
-    opts.banner = "Usage: #{prog} extract [options]"
-    opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') { |v| o[:source_dir] = v }
-    opts.on('-t DIR', '--target-dir DIR', 'Directory where the XHTML files will be extracted to (required)') { |v| o[:target_dir] = v }
-    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
-  end
-  EpubTools::XHTMLExtractor.new(
-    source_dir: options[:source_dir],
-    target_dir: options[:target_dir],
-    verbose: options[:verbose]
-  ).extract_all
-
-when 'split'
-  options = { output_dir: './chapters', prefix: 'chapter', verbose: true }
-  EpubTools::CLIHelper.parse(options, [:input_file, :book_title]) do |opts, o|
-    opts.banner = "Usage: #{prog} split [options]"
-    opts.on('-i FILE', '--input FILE', 'Source XHTML file (required)') { |v| options[:input_file] = v }
-    opts.on('-t TITLE', '--title TITLE', 'Book title for HTML <title> tags (required)') { |v| options[:book_title] = v }
-    opts.on('-o DIR', '--output-dir DIR', "Output directory for chapter files (default: #{options[:output_dir]})") { |v| options[:output_dir] = v }
-    opts.on('-p PREFIX', '--prefix PREFIX', "Filename prefix for chapters (default: #{options[:prefix]})") { |v| options[:prefix] = v }
-    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
-  end
-  EpubTools::SplitChapters.new(options[:input_file], options[:book_title], options[:output_dir], options[:prefix], options[:verbose]).run
-
-when 'init'
-  options = {}
-  EpubTools::CLIHelper.parse(options, [:title, :author, :destination]) do |opts, o|
-    opts.banner = "Usage: #{prog} init [options]"
-    opts.on('-t TITLE', '--title TITLE', 'Book title (required)') { |v| o[:title] = v }
-    opts.on('-a AUTHOR', '--author AUTHOR', 'Author name (required)') { |v| o[:author] = v }
-    opts.on('-o DIR', '--output-dir DIR', 'Destination EPUB directory (required)') { |v| o[:destination] = v }
-    opts.on('-c PATH', '--cover PATH', 'Cover image file path (optional)') { |v| o[:cover_image] = v }
-  end
-
-  EpubTools::EpubInitializer.new(options[:title], options[:author], options[:destination], options[:cover_image]).run
-
-when 'pack'
-  options = {verbose: true}
-  EpubTools::CLIHelper.parse(options, [:input_dir, :output_file]) do |opts, o|
-    opts.banner = "Usage: #{prog} pack [options]"
-    opts.on('-i DIR', '--input-dir DIR', 'EPUB directory to package (required)') { |v| o[:input_dir] = v }
-    opts.on('-o FILE', '--output-file FILE', 'Output EPUB file path (required)') { |v| o[:output_file] = v }
-    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
-  end
-
-  EpubTools::PackEbook.new(options[:input_dir], options[:output_file], verbose: options[:verbose]).run
-
-when 'unpack'
-  options = {verbose: true}
-  EpubTools::CLIHelper.parse(options, [:epub_file]) do |opts, o|
-    opts.banner = "Usage: #{prog} unpack [options]"
-    opts.on('-i FILE', '--input-file FILE', 'EPUB file to unpack (required)') { |v| o[:epub_file] = v }
-    opts.on('-o DIR', '--output-dir DIR', 'Output directory to extract into (default: basename of epub)') { |v| o[:output_dir] = v }
-    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
-  end
-  EpubTools::UnpackEbook.new(options[:epub_file], options[:output_dir], verbose: options[:verbose]).run
-
-when 'compile'
-  options = {verbose: true}
-  EpubTools::CLIHelper.parse(options, %i(title author source_dir)) do |opts, o|
-    opts.banner = "Usage: #{prog} compile [options]"
-    opts.on('-t TITLE', '--title TITLE', 'Book title (required)') { |v| o[:title] = v }
-    opts.on('-a AUTHOR', '--author AUTHOR', 'Author name (required)') { |v| o[:author] = v }
-    opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') { |v| o[:source_dir] = v }
-    opts.on('-o FILE', '--output FILE', 'EPUB to create (default: book title in source dir)') { |v| o[:output_file] = v }
-    opts.on('-c PATH', '--cover PATH', 'Cover image file path (optional)') { |v| o[:cover_image] = v }
-    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
-  end
-  EpubTools::CompileBook.new(**options).run
-end
+# Use the new object-oriented CLI architecture
+runner = EpubTools::CLI.create_runner
+runner.run(ARGV)

data/epub_tools.gemspec

@@ -11,16 +11,14 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split("\n")
   spec.require_paths = ['lib']
   spec.executables   = ['epub-tools']
-  spec.required_ruby_version = ">= 3.2"
-  spec.metadata    = {
-    "source_code_uri" => "https://github.com/jaimerodas/epub_tools/tree/main",
-    "homepage_uri" => "https://github.com/jaimerodas/epub_tools"
+  spec.required_ruby_version = '>= 3.2'
+  spec.metadata = {
+    'source_code_uri' => 'https://github.com/jaimerodas/epub_tools/tree/main',
+    'homepage_uri' => 'https://github.com/jaimerodas/epub_tools',
+    'rubygems_mfa_required' => 'true'
   }
 
   spec.add_dependency 'nokogiri', '~> 1.18'
-  spec.add_dependency 'rubyzip', '~> 2.4'
   spec.add_dependency 'rake', '~> 13.2'
-
-  spec.add_development_dependency 'minitest', '~> 5.25'
-  spec.add_development_dependency 'simplecov', '~> 0'
+  spec.add_dependency 'rubyzip', '~> 2.4'
 end

data/lib/epub_tools/add_chapters.rb

@@ -1,24 +1,29 @@
 #!/usr/bin/env ruby
 require 'nokogiri'
 require 'fileutils'
+require_relative 'loggable'
 
 module EpubTools
   # Moves new chapters into an unpacked EPUB
   class AddChapters
-    # :args: chapters_dir, epub_dir, verbose:
-    # [chapters_dir] Directory from which to move the xhtml chapters. It assumes the
-    #                directory will contain one or more files named +chapter_XX.xhtml+,
-    #                where +XX+ is a number. Defaults to +./chapters+.
-    # [epub_dir] Unpacked EPUB directory to move the chapters to. It should be the same
-    #            directory that contains the +package.opf+ and +nav.xhtml+ files. Defaults
-    #            to +./epub/OEBPS+.
-    # [verbose:] Whether to log progress to +STDOUT+ or not. Defaults to +false+.
-    def initialize(chapters_dir = './chapters', epub_dir = './epub/OEBPS', verbose = false)
-      @chapters_dir = chapters_dir
-      @epub_dir = epub_dir
+    include Loggable
+    # Initializes the class
+    # @param options [Hash] Configuration options
+    # @option options [String] :chapters_dir Directory from which to move the xhtml chapters.
+    #                          It assumes the directory will contain one or more files named
+    #                          +chapter_XX.xhtml+, where +XX+ is a number. (default: './chapters')
+    # @option options [String] :epub_dir Unpacked EPUB directory to move the chapters to. It should
+    #                          be the same directory that contains the +package.opf+ and +nav.xhtml+
+    #                          files. (default: './epub/OEBPS')
+    # @option options [Boolean] :verbose Whether to log progress to STDOUT (default: false)
+    def initialize(options = {})
+      @chapters_dir = File.expand_path(options[:chapters_dir] || './chapters')
+      @epub_dir = File.expand_path(options[:oebps_dir] || './epub/OEBPS')
       @opf_file = File.join(@epub_dir, 'package.opf')
       @nav_file = File.join(@epub_dir, 'nav.xhtml')
-      @verbose = verbose
+      @verbose = options[:verbose] || false
+
+      validate_directories!
     end
 
     # It works like this:
@@ -27,21 +32,38 @@ module EpubTools
     #   It will sort the files by extracting the chapter number.
     # - Finally, it will update the +nav.xhtml+ file with the new chapters. Note that if there's a
     #   file named +chapter_0.xhtml+, it will be added to the +nav.xhtml+ as the Prologue.
+    # @return [Array<String>] List of moved chapter filenames
     def run
       moved_files = move_chapters
       update_package_opf(moved_files)
       update_nav_xhtml(moved_files)
-      @verbose ? moved_files.each {|f| puts "Moved: #{f}"} : moved_files
+      moved_files.each { |f| log("Moved: #{f}") }
+      moved_files
     end
 
     private
 
+    def validate_directories!
+      raise ArgumentError, "Chapters directory '#{@chapters_dir}' does not exist" unless Dir.exist?(@chapters_dir)
+
+      raise ArgumentError, "EPUB directory '#{@epub_dir}' does not exist" unless Dir.exist?(@epub_dir)
+
+      raise ArgumentError, "EPUB package.opf file missing at '#{@opf_file}'" unless File.exist?(@opf_file)
+
+      return if File.exist?(@nav_file)
+
+      raise ArgumentError, "EPUB nav.xhtml file missing at '#{@nav_file}'"
+    end
+
     def move_chapters
       # Sort by chapter number (numeric)
       chapter_files = Dir.glob(File.join(@chapters_dir, '*.xhtml')).sort_by do |path|
         # extract first integer from filename (e.g. chapter_10.xhtml -> 10)
         File.basename(path)[/\d+/].to_i
       end
+
+      raise ArgumentError, "No .xhtml files found in '#{@chapters_dir}'" if chapter_files.empty?
+
       chapter_files.each do |file|
         FileUtils.mv(file, @epub_dir)
       end
@@ -70,11 +92,11 @@ module EpubTools
         end
 
         # Add <itemref> to the spine if missing
-        unless doc.at_xpath("//xmlns:itemref[@idref='#{id}']")
-          itemref = Nokogiri::XML::Node.new('itemref', doc)
-          itemref['idref'] = id
-          spine.add_child(itemref)
-        end
+        next if doc.at_xpath("//xmlns:itemref[@idref='#{id}']")
+
+        itemref = Nokogiri::XML::Node.new('itemref', doc)
+        itemref['idref'] = id
+        spine.add_child(itemref)
       end
 
       File.write(@opf_file, doc.to_xml(indent: 2))
@@ -87,7 +109,7 @@ module EpubTools
       filenames.each do |filename|
         # Create a new <li><a href="...">Label</a></li> element
         label = File.basename(filename, '.xhtml').gsub('_', ' ').capitalize
-        label = "Prologue" if label == "Chapter 0"
+        label = 'Prologue' if label == 'Chapter 0'
         li = Nokogiri::XML::Node.new('li', doc)
         a  = Nokogiri::XML::Node.new('a', doc)
         a['href'] = filename

data/lib/epub_tools/cli/command_registry.rb

@@ -0,0 +1,47 @@
+module EpubTools
+  module CLI
+    # Manages the registration and retrieval of commands
+    class CommandRegistry
+      attr_reader :commands
+
+      def initialize
+        @commands = {}
+      end
+
+      # Register a new command in the registry
+      # @param name [String] the command name
+      # @param command_class [Class] the class that implements the command
+      # @param required_keys [Array<Symbol>] keys that must be present in options
+      # @param default_options [Hash] default options for the command
+      # @return [self]
+      def register(name, command_class, required_keys = [], default_options = {})
+        @commands[name] = {
+          class: command_class,
+          required_keys: required_keys,
+          default_options: default_options
+        }
+        self
+      end
+
+      # Get a command by name
+      # @param name [String] the command name
+      # @return [Hash, nil] the command configuration or nil if not found
+      def get(name)
+        @commands[name]
+      end
+
+      # Get all available command names
+      # @return [Array<String>] list of registered command names
+      def available_commands
+        @commands.keys
+      end
+
+      # Check if a command is registered
+      # @param name [String] the command name
+      # @return [Boolean] true if command exists
+      def command_exists?(name)
+        @commands.key?(name)
+      end
+    end
+  end
+end