epub_tools 0.5.0 → 0.9.0

data/lib/epub_tools/book_builder.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'loggable'
+require_relative 'xhtml_extractor'
+require_relative 'split_chapters'
+require_relative 'pdf_converter'
+require_relative 'add_chapters'
+require_relative 'pack_ebook'
+require_relative 'chapter_validator'
+
+module EpubTools
+  # Base class for book-building workflows (compile and append). Sources can be EPUBs (split into chapters)
+  # and/or chapter PDFs (see {PDFConverter}[rdoc-ref:EpubTools::PDFConverter] for the naming convention).
+  # Uses template method pattern — subclasses override hooks to customize behavior.
+  class BookBuilder
+    include Loggable
+
+    attr_reader :source_dir, :build_dir, :verbose
+
+    def initialize(options = {})
+      @source_dir = options.fetch(:source_dir)
+      @build_dir  = options[:build_dir] || File.join(Dir.pwd, '.epub_tools_build')
+      @verbose    = options[:verbose] || false
+    end
+
+    # Run the full build workflow
+    # @return [String] Path to the output EPUB file
+    def run
+      setup_workspace
+      prepare_epub
+      extract_xhtmls
+      split_xhtmls
+      convert_pdfs
+      validate_chapters
+      before_add_chapters
+      add_chapters
+      pack_epub
+      finalize_and_cleanup
+    end
+
+    private
+
+    # Hook: called before extract/split to set up the EPUB target
+    def prepare_epub; end
+
+    # Hook: called after validation, before adding chapters
+    def before_add_chapters; end
+
+    # Subclasses also define +book_title+ (used when splitting chapters) and +output_path+ (the EPUB to write)
+
+    def setup_workspace
+      FileUtils.rm_rf(build_dir)
+      FileUtils.mkdir_p([xhtml_dir, chapters_dir])
+      log 'Preparing build directories...'
+    end
+
+    def extract_xhtmls
+      log "Extracting XHTML files from EPUBs in '#{source_dir}'..."
+      XHTMLExtractor.new(source_dir: source_dir, target_dir: xhtml_dir, verbose: verbose).run
+    end
+
+    def split_xhtmls
+      Dir.glob(File.join(xhtml_dir, '*.xhtml')).each { |f| split_xhtml_file(f) }
+    end
+
+    def split_xhtml_file(xhtml_file)
+      log "Splitting '#{File.basename(xhtml_file, '.xhtml')}'..."
+      SplitChapters.new(
+        input_file: xhtml_file, book_title: book_title,
+        output_dir: chapters_dir, verbose: verbose
+      ).run
+    end
+
+    def convert_pdfs
+      return if Dir.glob(File.join(source_dir, '*.pdf')).empty?
+
+      log "Converting PDFs in '#{source_dir}'..."
+      PDFConverter.new(
+        source_dir: source_dir, book_title: book_title, output_dir: chapters_dir, verbose: verbose
+      ).run
+    end
+
+    def validate_chapters
+      ChapterValidator.new(chapters_dir: chapters_dir, verbose: verbose).validate
+    end
+
+    def add_chapters
+      log 'Adding chapters to EPUB...'
+      AddChapters.new(
+        chapters_dir: chapters_dir,
+        oebps_dir: epub_oebps_dir,
+        verbose: verbose
+      ).run
+    end
+
+    def pack_epub
+      log "Building EPUB '#{output_path}'..."
+      # Expanded here: PackEbook puts a relative path next to epub_dir, inside the build dir that gets deleted
+      PackEbook.new(input_dir: epub_dir, output_file: File.expand_path(output_path), verbose: verbose).run
+    end
+
+    def finalize_and_cleanup
+      log "Done. Output EPUB: #{File.expand_path(output_path)}"
+      FileUtils.rm_rf(build_dir)
+      output_path
+    end
+
+    def xhtml_dir = File.join(build_dir, 'xhtml')
+    def chapters_dir = File.join(build_dir, 'chapters')
+    def epub_dir = File.join(build_dir, 'epub')
+    def epub_oebps_dir = File.join(epub_dir, 'OEBPS')
+  end
+end

data/lib/epub_tools/chapter_order.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module EpubTools
+  # Reading order of chapter files: chapter_1, chapter_1_5, chapter_1a, chapter_1b, chapter_2, ..., chapter_epilogue
+  module ChapterOrder
+    module_function
+
+    # @param filename [String] A chapter filename, e.g. +chapter_12a.xhtml+
+    # @return [Array] A key that sorts chapter filenames in reading order
+    def sort_key(filename)
+      basename = File.basename(filename, '.xhtml')
+      return [Float::INFINITY, ''] if basename == 'chapter_epilogue'
+
+      if (m = basename.match(/_(\d+)_5\z/))
+        [m[1].to_f + 0.5, '']
+      else
+        [basename[/\d+/].to_f, basename[/\d+([a-z]*)\z/, 1].to_s]
+      end
+    end
+
+    # Inserts +node+ into +parent+ before the first chapter that sorts after +filename+, so a chapter added
+    # later (e.g. 12a after 13 is already in the book) still lands in reading order.
+    # @yield [element] Each existing child element; returns the filename it points to
+    def insert(parent, node, filename)
+      key = sort_key(filename)
+      later = parent.element_children.find do |el|
+        href = yield(el)
+        href&.start_with?('chapter_') && (sort_key(href) <=> key) == 1
+      end
+      later ? later.add_previous_sibling(node) : parent.add_child(node)
+    end
+  end
+end

data/lib/epub_tools/chapter_validator.rb

@@ -12,28 +12,41 @@ module EpubTools
       @verbose = verbose
     end
 
+    # Validates that integer chapter numbers form a complete sequence with no gaps.
+    # Half-chapters (e.g. chapter_5_5.xhtml) and lettered side chapters (e.g. chapter_5a.xhtml) are
+    # recognized but not required.
+    # @raise [RuntimeError] if no chapter files are found or if integer chapters have gaps
     def validate
       log 'Validating chapter sequence...'
       nums = extract_chapter_numbers
       check_sequence_completeness(nums)
-      log "Chapter sequence is complete: #{nums.first} to #{nums.last}."
+      log "Chapter sequence is complete: #{nums.first.floor} to #{nums.last.floor}."
     end
 
     private
 
     def extract_chapter_numbers
-      nums = Dir.glob(File.join(@chapters_dir, '*.xhtml')).map do |file|
-        if (m = File.basename(file, '.xhtml').match(/_(\d+)\z/))
-          m[1].to_i
-        end
-      end.compact
+      nums = Dir.glob(File.join(@chapters_dir, '*.xhtml')).filter_map do |file|
+        extract_chapter_number(File.basename(file, '.xhtml'))
+      end
       raise "No chapter files found in #{@chapters_dir}" if nums.empty?
 
       nums.sort.uniq
     end
 
+    def extract_chapter_number(basename)
+      if (m = basename.match(/_(\d+)(?:_5|[a-z]+)\z/))
+        m[1].to_i + 0.5
+      elsif (m = basename.match(/_(\d+)\z/))
+        m[1].to_i
+      end
+    end
+
     def check_sequence_completeness(sorted)
-      missing = (sorted.first..sorted.last).to_a - sorted
+      integers = sorted.select { |n| n == n.to_i }.map(&:to_i)
+      return if integers.empty? # e.g. appending only side chapters
+
+      missing = (integers.first..integers.last).to_a - integers
       raise "Missing chapter numbers: #{missing.join(' ')}" if missing.any?
     end
   end

data/lib/epub_tools/cli.rb

@@ -1,32 +1,131 @@
 # frozen_string_literal: true
 
-require_relative 'cli/command_registry'
-require_relative 'cli/option_builder'
-require_relative 'cli/runner'
+require 'optparse'
+require_relative 'version'
+require_relative 'epub_initializer'
+require_relative 'xhtml_extractor'
+require_relative 'split_chapters'
+require_relative 'pdf_converter'
+require_relative 'add_chapters'
+require_relative 'pack_ebook'
+require_relative 'unpack_ebook'
+require_relative 'set_cover'
+require_relative 'compile_book'
+require_relative 'append_book'
 
 module EpubTools
-  # CLI module - houses the object-oriented command line interface components
+  # Command line interface: parses a command's flags and runs the class that implements it
   module CLI
-    # Create a new Runner instance configured with all available commands
-    # @param program_name [String] Name of the program
-    # @return [CLI::Runner] A configured runner instance
-    def self.create_runner(program_name = nil)
-      runner = Runner.new(program_name)
-      register_all_commands(runner.registry)
-      runner
+    TITLE = ['-t TITLE', '--title TITLE', 'Book title', :title, :required].freeze
+    AUTHOR = ['-a AUTHOR', '--author AUTHOR', 'Author name', :author, :required].freeze
+    COVER = ['-c PATH', '--cover PATH', 'Cover image file path (optional)', :cover_image].freeze
+    BOOK_TITLE = ['-t TITLE', '--title TITLE', 'Book title for HTML <title> tags', :book_title, :required].freeze
+    CHAPTERS_OUT = ['-o DIR', '--output-dir DIR', 'Output directory for chapter files (default: ./chapters)',
+                    :output_dir].freeze
+
+    # Each command's class, usage summary and flags as [short, long, description, option key, :required].
+    # Commands log progress unless run with -q, except those marked <tt>verbose: false</tt>.
+    COMMANDS = {
+      'init' => { class: EpubInitializer, summary: 'Initialize a bare-bones EPUB',
+                  flags: [TITLE, AUTHOR, ['-o DIR', '--output-dir DIR', 'Destination EPUB directory',
+                                          :destination, :required], COVER] },
+      'extract' => { class: XHTMLExtractor, summary: 'Extract XHTML files from EPUBs',
+                     flags: [['-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from',
+                              :source_dir, :required],
+                             ['-t DIR', '--target-dir DIR',
+                              'Directory where the XHTML files will be extracted to', :target_dir, :required]] },
+      'split' => { class: SplitChapters, summary: 'Split XHTML into separate XHTMLs per chapter',
+                   flags: [['-i FILE', '--input FILE', 'Source XHTML file', :input_file, :required], BOOK_TITLE,
+                           CHAPTERS_OUT] },
+      'pdf' => { class: PDFConverter, summary: 'Convert chapter PDFs into chapter XHTMLs',
+                 flags: [['-s DIR', '--source-dir DIR', "Dir of PDFs named '12a Title.pdf'", :source_dir, :required],
+                         BOOK_TITLE, CHAPTERS_OUT] },
+      'add' => { class: AddChapters, summary: 'Add chapter XHTML files into an EPUB', verbose: false,
+                 flags: [['-c DIR', '--chapters-dir DIR', 'Chapters directory', :chapters_dir, :required],
+                         ['-e DIR', '--oebps-dir DIR', 'EPUB OEBPS directory', :oebps_dir, :required]] },
+      'pack' => { class: PackEbook, summary: 'Package an EPUB directory into a .epub file',
+                  flags: [['-i DIR', '--input-dir DIR', 'EPUB directory to package', :input_dir, :required],
+                          ['-o FILE', '--output-file FILE', 'Output EPUB file path', :output_file, :required]] },
+      'unpack' => { class: UnpackEbook, summary: 'Unpack an EPUB file into a directory',
+                    flags: [['-i FILE', '--input-file FILE', 'EPUB file to unpack', :epub_file, :required],
+                            ['-o DIR', '--output-dir DIR',
+                             'Output directory to extract into (default: basename of epub)', :output_dir]] },
+      'cover' => { class: SetCover, summary: 'Add or replace the cover of an EPUB',
+                   flags: [['-i FILE', '--input-file FILE', 'EPUB to add the cover to', :epub_file, :required],
+                           ['-c PATH', '--cover PATH', 'Cover image: jpg, png, gif or svg', :cover_image, :required]] },
+      'compile' => { class: CompileBook,
+                     summary: 'Takes EPUBs and/or chapter PDFs in a dir and compiles them into a single EPUB.',
+                     flags: [TITLE, AUTHOR,
+                             ['-s DIR', '--source-dir DIR', 'Directory with EPUBs and/or chapter PDFs',
+                              :source_dir, :required],
+                             ['-o FILE', '--output FILE', 'EPUB to create (default: <Book_Title>.epub)',
+                              :output_file], COVER] },
+      'append' => { class: AppendBook,
+                    summary: 'Takes EPUBs and/or chapter PDFs in a dir and appends them to an existing EPUB.',
+                    flags: [['-s DIR', '--source-dir DIR',
+                             'Directory with EPUBs and/or chapter PDFs to append', :source_dir, :required],
+                            ['-t FILE', '--target-epub FILE', 'Existing EPUB file to append to',
+                             :target_epub, :required]] }
+    }.freeze
+
+    module_function
+
+    # Runs the command named by the first argument, or prints the version or usage
+    # @param args [Array<String>] Command line arguments
+    # @return [Object] The command instance that ran
+    def run(args)
+      if ['-v', '--version'].include?(args[0])
+        puts VERSION
+        exit
+      end
+      usage unless COMMANDS.key?(args[0])
+
+      name, *rest = args
+      COMMANDS[name][:class].new(parse(name, rest)).tap(&:run)
+    end
+
+    # @param name [String] Command name
+    # @param args [Array<String>] The command's arguments
+    # @return [Hash] Options for the command's class; exits with the help text if they are invalid
+    def parse(name, args)
+      command = COMMANDS.fetch(name)
+      options = verbose?(command) ? { verbose: true } : {}
+      parser = parser_for(name, command, options)
+      parser.parse(args)
+      missing = missing_flags(command, options)
+      abort "Missing required options: #{missing.join(', ')}\n#{parser}" if missing.any?
+
+      options
+    rescue OptionParser::ParseError => e
+      abort "#{e.message}\n#{parser}"
     end
 
-    # Register all available commands with their configurations
-    # @param registry [CommandRegistry] The command registry to populate
-    def self.register_all_commands(registry)
-      registry.register('add', EpubTools::AddChapters, %i[chapters_dir oebps_dir])
-      registry.register('extract', EpubTools::XHTMLExtractor, %i[source_dir target_dir], { verbose: true })
-      registry.register('split', EpubTools::SplitChapters, %i[input_file book_title],
-                        { output_dir: './chapters', prefix: 'chapter', verbose: true })
-      registry.register('init', EpubTools::EpubInitializer, %i[title author destination], { verbose: true })
-      registry.register('pack', EpubTools::PackEbook, %i[input_dir output_file], { verbose: true })
-      registry.register('unpack', EpubTools::UnpackEbook, [:epub_file], { verbose: true })
-      registry.register('compile', EpubTools::CompileBook, %i[title author source_dir], { verbose: true })
+    # @return [Array<String>] The long names of required flags that were not given, e.g. +--title+
+    def missing_flags(command, options)
+      command[:flags].filter_map { |_, long, _, key, required| long.split.first if required && options[key].nil? }
     end
+
+    def parser_for(name, command, options)
+      OptionParser.new("Usage: #{program_name} #{name} [options]") do |parser|
+        command[:flags].each do |short, long, desc, key, required|
+          parser.on(short, long, required ? "#{desc} (required)" : desc) { |v| options[key] = v }
+        end
+        parser.on('-q', '--quiet', 'Run quietly (default: verbose)') { options[:verbose] = false } if verbose?(command)
+        parser.on('-h', '--help', 'Print this help') do
+          puts parser
+          exit
+        end
+      end
+    end
+
+    def usage
+      puts "Usage: #{program_name} COMMAND [options]", 'Commands:'
+      COMMANDS.each { |name, command| puts "  #{name.ljust(9)} #{command[:summary]}" }
+      exit 1
+    end
+
+    def verbose?(command) = command.fetch(:verbose, true)
+
+    def program_name = File.basename($PROGRAM_NAME)
   end
 end

data/lib/epub_tools/compile_book.rb

@@ -1,150 +1,36 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'fileutils'
-require_relative 'loggable'
-require_relative 'xhtml_extractor'
-require_relative 'split_chapters'
+require_relative 'book_builder'
 require_relative 'epub_initializer'
-require_relative 'add_chapters'
-require_relative 'pack_ebook'
-require_relative 'compile_workspace'
-require_relative 'chapter_validator'
 
 module EpubTools
-  # Orchestrates extraction, splitting, validation, and packaging of book EPUBs
-  class CompileBook
-    include Loggable
+  # Compiles a new EPUB from source EPUBs by extracting, splitting, and repackaging
+  class CompileBook < BookBuilder
+    attr_reader :title, :author, :cover_image, :output_file
 
-    # Book title
-    attr_reader :title
-    # Book author
-    attr_reader :author
-    # Path of the input epubs
-    attr_reader :source_dir
-    # Optional path to the cover image
-    attr_reader :cover_image
-    # Filename for the final epub
-    attr_reader :output_file
-    # Optional working directory for intermediate files
-    attr_reader :build_dir
-    # Whether to print progress to STDOUT
-    attr_reader :verbose
-
-    # Initializes the class
-    # @param options [Hash] Configuration options
-    # @option options [String] :title Book title (required)
-    # @option options [String] :author Book author (required)
-    # @option options [String] :source_dir Path of the input epubs (required)
-    # @option options [String] :cover_image Optional path to the cover image
-    # @option options [String] :output_file Filename for the final epub (default: [title].epub)
-    # @option options [String] :build_dir Optional working directory for intermediate files
-    # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
     def initialize(options = {})
+      super
       @title       = options.fetch(:title)
       @author      = options.fetch(:author)
-      @source_dir  = options.fetch(:source_dir)
       @cover_image = options[:cover_image]
       @output_file = options[:output_file] || default_output_file
-      @build_dir   = options[:build_dir] || File.join(Dir.pwd, '.epub_tools_build')
-      @verbose     = options[:verbose] || false
-      @workspace   = CompileWorkspace.new(@build_dir)
-    end
-
-    # Run the full compile workflow
-    def run
-      setup_workspace
-      extract_xhtmls
-      split_xhtmls
-      validate_chapters
-      initialize_epub
-      add_chapters
-      pack_epub
-      finalize_and_cleanup
     end
 
     private
 
-    def setup_workspace
-      @workspace.clean
-      log "Cleaning build directory #{@build_dir}..."
-      @workspace.prepare_directories
-      log 'Preparing build directories...'
-    end
+    def book_title = @title
 
-    def finalize_and_cleanup
-      log "Done. Output EPUB: #{File.expand_path(output_file)}"
-      @workspace.clean
-      output_file
-    end
-
-    def default_output_file
-      "#{title.gsub(' ', '_')}.epub"
-    end
-
-    def extract_xhtmls
-      log "Extracting XHTML files from epubs in '#{source_dir}'..."
-      XHTMLExtractor.new({
-                           source_dir: source_dir,
-                           target_dir: @workspace.xhtml_dir,
-                           verbose: verbose
-                         }).run
-    end
-
-    def split_xhtmls
-      log 'Splitting XHTML files into chapters...'
-      Dir.glob(File.join(@workspace.xhtml_dir, '*.xhtml')).each do |xhtml_file|
-        split_xhtml_file(xhtml_file)
-      end
-    end
+    def output_path = @output_file
 
-    def split_xhtml_file(xhtml_file)
-      base = File.basename(xhtml_file, '.xhtml')
-      log "Splitting '#{base}'..."
-      SplitChapters.new(build_split_options(xhtml_file)).run
-    end
-
-    def build_split_options(xhtml_file)
-      {
-        input_file: xhtml_file,
-        book_title: title,
-        output_dir: @workspace.chapters_dir,
-        output_prefix: 'chapter',
-        verbose: verbose
-      }
-    end
-
-    def validate_chapters
-      ChapterValidator.new(chapters_dir: @workspace.chapters_dir, verbose: verbose).validate
-    end
-
-    def initialize_epub
+    def before_add_chapters
       log 'Initializing new EPUB...'
-      EpubInitializer.new(build_epub_options).run
-    end
-
-    def build_epub_options
-      options = { title: title, author: author, destination: @workspace.epub_dir }
+      options = { title: title, author: author, destination: epub_dir }
       options[:cover_image] = cover_image if cover_image
-      options
-    end
-
-    def add_chapters
-      log 'Adding chapters to EPUB...'
-      AddChapters.new({
-                        chapters_dir: @workspace.chapters_dir,
-                        epub_dir: File.join(@workspace.epub_dir, 'OEBPS'),
-                        verbose: verbose
-                      }).run
+      EpubInitializer.new(options).run
     end
 
-    def pack_epub
-      log "Building final EPUB '#{output_file}'..."
-      PackEbook.new({
-                      input_dir: @workspace.epub_dir,
-                      output_file: output_file,
-                      verbose: verbose
-                    }).run
+    def default_output_file
+      "#{title.gsub(' ', '_')}.epub"
     end
   end
 end