epub_tools 0.4.1 → 0.6.0

data/lib/epub_tools/append_book.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require_relative 'book_builder'
+require_relative 'unpack_ebook'
+
+module EpubTools
+  # Appends chapters from source EPUBs to an existing target EPUB
+  class AppendBook < BookBuilder
+    attr_reader :target_epub
+
+    def initialize(options = {})
+      super
+      @target_epub = File.expand_path(options.fetch(:target_epub))
+    end
+
+    private
+
+    def book_title
+      @book_title ||= read_target_title
+    end
+
+    def output_path = @target_epub
+
+    def prepare_epub
+      backup_target
+      unpack_target
+    end
+
+    def before_add_chapters
+      detect_conflicts
+    end
+
+    def finalize_and_cleanup
+      log "Done. Updated EPUB: #{@target_epub} (backup: #{@backup_path})"
+      @workspace.clean
+      @target_epub
+    end
+
+    def backup_target
+      @backup_path = "#{@target_epub}.bak"
+      log "Backing up target to '#{@backup_path}'..."
+      FileUtils.cp(@target_epub, @backup_path)
+    end
+
+    def unpack_target
+      log 'Unpacking target EPUB...'
+      UnpackEbook.new(epub_file: @target_epub, output_dir: @workspace.epub_dir, verbose: verbose).run
+    end
+
+    def read_target_title
+      opf_path = File.join(epub_oebps_dir, 'package.opf')
+      doc = Nokogiri::XML(File.read(opf_path))
+      doc.remove_namespaces!
+      doc.at_xpath('//title')&.text || 'Untitled'
+    end
+
+    def detect_conflicts
+      new_numbers = chapter_numbers_in(@workspace.chapters_dir)
+      existing_numbers = chapter_numbers_in(epub_oebps_dir)
+      conflicts = new_numbers & existing_numbers
+      return if conflicts.empty?
+
+      formatted = conflicts.sort.map { |n| n == n.to_i ? n.to_i.to_s : n.to_s }
+      raise ArgumentError,
+            "Chapter number conflict: chapters #{formatted.join(', ')} already exist in the target EPUB. " \
+            'Renumber the source chapters or remove conflicting chapters from the target.'
+    end
+
+    def chapter_numbers_in(dir)
+      Dir.glob(File.join(dir, 'chapter_*.xhtml')).filter_map do |path|
+        basename = File.basename(path, '.xhtml')
+        if (m = basename.match(/_(\d+)_5\z/))
+          m[1].to_f + 0.5
+        elsif (m = basename.match(/_(\d+)\z/))
+          m[1].to_f
+        end
+      end
+    end
+  end
+end

data/lib/epub_tools/book_builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'loggable'
+require_relative 'xhtml_extractor'
+require_relative 'split_chapters'
+require_relative 'add_chapters'
+require_relative 'pack_ebook'
+require_relative 'compile_workspace'
+require_relative 'chapter_validator'
+
+module EpubTools
+  # Base class for book-building workflows (compile and append).
+  # 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
+      @workspace  = CompileWorkspace.new(@build_dir)
+    end
+
+    # Run the full build workflow
+    # @return [String] Path to the output EPUB file
+    def run
+      setup_workspace
+      prepare_epub
+      extract_xhtmls
+      split_xhtmls
+      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 must implement: the book title used when splitting chapters
+    def book_title
+      raise NotImplementedError, "#{self.class} must implement #book_title"
+    end
+
+    # Subclasses must implement: the output file path for pack_epub
+    def output_path
+      raise NotImplementedError, "#{self.class} must implement #output_path"
+    end
+
+    def setup_workspace
+      @workspace.clean
+      @workspace.prepare_directories
+      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: @workspace.xhtml_dir, verbose: verbose).run
+    end
+
+    def split_xhtmls
+      Dir.glob(File.join(@workspace.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: @workspace.chapters_dir, output_prefix: 'chapter', verbose: verbose
+      ).run
+    end
+
+    def validate_chapters
+      ChapterValidator.new(chapters_dir: @workspace.chapters_dir, verbose: verbose).validate
+    end
+
+    def add_chapters
+      log 'Adding chapters to EPUB...'
+      AddChapters.new(
+        chapters_dir: @workspace.chapters_dir,
+        oebps_dir: epub_oebps_dir,
+        verbose: verbose
+      ).run
+    end
+
+    def pack_epub
+      log "Building EPUB '#{output_path}'..."
+      PackEbook.new(input_dir: @workspace.epub_dir, output_file: output_path, verbose: verbose).run
+    end
+
+    def finalize_and_cleanup
+      log "Done. Output EPUB: #{File.expand_path(output_path)}"
+      @workspace.clean
+      output_path
+    end
+
+    def epub_oebps_dir = File.join(@workspace.epub_dir, 'OEBPS')
+  end
+end

data/lib/epub_tools/chapter_marker_detector.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module EpubTools
+  # Detects chapter boundary markers in XHTML nodes.
+  # Recognizes: "Chapter N", "Chapter N (continued)", and "Prologue".
+  class ChapterMarkerDetector
+    # Tags that can contain chapter markers
+    MARKER_TAGS = %w[p span h2 h3 h4].freeze
+    # Tags that can contain prologue markers
+    PROLOGUE_TAGS = %w[h3 h4].freeze
+
+    # Detect what type of chapter marker a node represents
+    # @param node [Nokogiri::XML::Node] The XHTML node to check
+    # @return [Symbol, nil] :chapter, :continued, :prologue, or nil
+    def detect(node)
+      if continued_marker?(node)
+        :continued
+      elsif chapter_marker?(node)
+        :chapter
+      elsif prologue_marker?(node)
+        :prologue
+      end
+    end
+
+    # Extract the chapter number from a node's text
+    # @param node [Nokogiri::XML::Node] A node containing "Chapter N" text
+    # @return [Integer] The chapter number
+    def extract_chapter_number(node)
+      node.text.match(/Chapter\s+(\d+)/i)[1].to_i
+    end
+
+    private
+
+    def continued_marker?(node)
+      MARKER_TAGS.include?(node.name) && node.text.match?(/Chapter\s+\d+\s*\(continued\)/i)
+    end
+
+    def chapter_marker?(node)
+      MARKER_TAGS.include?(node.name) && node.text.match?(/Chapter\s+\d+/i) && !continued_marker?(node)
+    end
+
+    def prologue_marker?(node)
+      PROLOGUE_TAGS.include?(node.name) && node.text.strip.match?(/\APrologue\z/i)
+    end
+  end
+end

data/lib/epub_tools/chapter_validator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'loggable'
+
+module EpubTools
+  # Validates chapter sequence completeness
+  class ChapterValidator
+    include Loggable
+
+    def initialize(chapters_dir:, verbose: false)
+      @chapters_dir = chapters_dir
+      @verbose = verbose
+    end
+
+    # Validates that integer chapter numbers form a complete sequence with no gaps.
+    # Half-chapters (e.g. chapter_5_5.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}."
+    end
+
+    private
+
+    def extract_chapter_numbers
+      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\z/))
+        m[1].to_i + 0.5
+      elsif (m = basename.match(/_(\d+)\z/))
+        m[1].to_i
+      end
+    end
+
+    def check_sequence_completeness(sorted)
+      integers = sorted.select { |n| n == n.to_i }.map(&:to_i)
+      missing = (integers.first..integers.last).to_a - integers
+      raise "Missing chapter numbers: #{missing.join(' ')}" if missing.any?
+    end
+  end
+end

data/lib/epub_tools/cli/command_options_configurator.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module EpubTools
+  module CLI
+    # Handles command-specific option configuration for CLI commands
+    class CommandOptionsConfigurator
+      # Configure command-specific options using dynamic dispatch
+      # @param cmd [String] Command name
+      # @param builder [OptionBuilder] Option builder instance
+      def configure(cmd, builder)
+        method_name = "configure_#{cmd.tr('-', '_')}_options"
+        raise ArgumentError, "Unknown command: #{cmd}" unless respond_to?(method_name, true)
+
+        send(method_name, builder)
+      end
+
+      private
+
+      # Configure options for the 'add' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_add_options(builder)
+        builder.with_custom_options do |opts, options|
+          opts.on('-c DIR', '--chapters-dir DIR', 'Chapters directory (required)') { |v| options[:chapters_dir] = v }
+          opts.on('-e DIR', '--oebps-dir DIR', 'EPUB OEBPS directory (required)') { |v| options[:oebps_dir] = v }
+        end
+      end
+
+      # Configure options for the 'extract' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_extract_options(builder)
+        builder.with_custom_options do |opts, options|
+          opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') do |v|
+            options[:source_dir] = v
+          end
+          opts.on('-t DIR', '--target-dir DIR',
+                  'Directory where the XHTML files will be extracted to (required)') do |v|
+            options[:target_dir] = v
+          end
+        end.with_verbose_option
+      end
+
+      # Configure options for the 'split' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_split_options(builder)
+        builder.with_custom_options do |opts, options|
+          add_split_input_options(opts, options)
+          add_split_output_options(opts, options)
+        end.with_verbose_option
+      end
+
+      def add_split_input_options(opts, 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)') do |v|
+          options[:book_title] = v
+        end
+      end
+
+      def add_split_output_options(opts, options)
+        opts.on('-o DIR', '--output-dir DIR',
+                "Output directory for chapter files (default: #{options[:output_dir]})") do |v|
+          options[:output_dir] = v
+        end
+        opts.on('-p PREFIX', '--prefix PREFIX', "Filename prefix for chapters (default: #{options[:prefix]})") do |v|
+          options[:prefix] = v
+        end
+      end
+
+      # Configure options for the 'init' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_init_options(builder)
+        builder.with_title_option
+               .with_author_option
+               .with_custom_options do |opts, options|
+                 opts.on('-o DIR', '--output-dir DIR', 'Destination EPUB directory (required)') do |v|
+                   options[:destination] = v
+                 end
+               end.with_cover_option
+      end
+
+      # Configure options for the 'pack' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_pack_options(builder)
+        builder.with_input_dir('EPUB directory to package')
+               .with_output_file('Output EPUB file path')
+               .with_verbose_option
+      end
+
+      # Configure options for the 'unpack' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_unpack_options(builder)
+        builder.with_custom_options do |opts, options|
+          opts.on('-i FILE', '--input-file FILE', 'EPUB file to unpack (required)') { |v| options[:epub_file] = v }
+          opts.on('-o DIR', '--output-dir DIR', 'Output directory to extract into (default: basename of epub)') do |v|
+            options[:output_dir] = v
+          end
+        end.with_verbose_option
+      end
+
+      # Configure options for the 'append' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_append_options(builder)
+        builder.with_custom_options do |opts, options|
+          opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to append (required)') do |v|
+            options[:source_dir] = v
+          end
+          opts.on('-t FILE', '--target-epub FILE', 'Existing EPUB file to append to (required)') do |v|
+            options[:target_epub] = v
+          end
+        end.with_verbose_option
+      end
+
+      # Configure options for the 'compile' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_compile_options(builder)
+        builder.with_title_option
+               .with_author_option
+               .with_custom_options do |opts, options|
+                 opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') do |v|
+                   options[:source_dir] = v
+                 end
+                 opts.on('-o FILE', '--output FILE', 'EPUB to create (default: book title in source dir)') do |v|
+                   options[:output_file] = v
+                 end
+               end.with_cover_option.with_verbose_option
+      end
+    end
+  end
+end

data/lib/epub_tools/cli/command_registry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module EpubTools
   module CLI
     # Manages the registration and retrieval of commands

data/lib/epub_tools/cli/option_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'optparse'
 
 module EpubTools
@@ -45,7 +47,7 @@ module EpubTools
       # @param description [String] Option description
       # @param required [Boolean] Whether this option is required
       # @return [self] for method chaining
-      def with_input_file(description = 'Input file', required = true)
+      def with_input_file(description = 'Input file', required: true)
         desc = required ? "#{description} (required)" : description
         @parser.on('-i FILE', '--input-file FILE', desc) { |v| @options[:input_file] = v }
         self
@@ -55,7 +57,7 @@ module EpubTools
       # @param description [String] Option description
       # @param required [Boolean] Whether this option is required
       # @return [self] for method chaining
-      def with_input_dir(description = 'Input directory', required = true)
+      def with_input_dir(description = 'Input directory', required: true)
         desc = required ? "#{description} (required)" : description
         @parser.on('-i DIR', '--input-dir DIR', desc) { |v| @options[:input_dir] = v }
         self
@@ -80,7 +82,7 @@ module EpubTools
       # @param description [String] Option description
       # @param required [Boolean] Whether this option is required
       # @return [self] for method chaining
-      def with_output_file(description = 'Output file', required = true)
+      def with_output_file(description = 'Output file', required: true)
         desc = required ? "#{description} (required)" : description
         @parser.on('-o FILE', '--output-file FILE', desc) { |v| @options[:output_file] = v }
         self

data/lib/epub_tools/cli/runner.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require_relative 'command_registry'
 require_relative 'option_builder'
+require_relative 'command_options_configurator'
 
 module EpubTools
   module CLI
@@ -12,24 +15,15 @@ module EpubTools
       def initialize(program_name = nil)
         @registry = CommandRegistry.new
         @program_name = program_name || File.basename($PROGRAM_NAME)
+        @options_configurator = CommandOptionsConfigurator.new
       end
 
       # Run the CLI application
       # @param args [Array<String>] Command line arguments
       # @return [Boolean] true if the command was run successfully
       def run(args = ARGV)
-        # Handle global version flag
-        if ['-v', '--version'].include?(args[0])
-          puts EpubTools::VERSION
-          exit 0
-        end
-
-        commands = registry.available_commands
-
-        if args.empty? || !commands.include?(args[0])
-          print_usage(commands)
-          exit 1
-        end
+        handle_version_flag(args)
+        validate_command_args(args)
 
         cmd = args.shift
         handle_command(cmd, args)
@@ -43,6 +37,36 @@ module EpubTools
         command_config = registry.get(cmd)
         return false unless command_config
 
+        builder = build_option_parser(cmd, command_config)
+        execute_command(command_config, builder, args)
+      end
+
+      private
+
+      # Handle version flag and exit if present
+      # @param args [Array<String>] Command line arguments
+      def handle_version_flag(args)
+        return unless ['-v', '--version'].include?(args[0])
+
+        puts EpubTools::VERSION
+        exit 0
+      end
+
+      # Validate command arguments and exit if invalid
+      # @param args [Array<String>] Command line arguments
+      def validate_command_args(args)
+        commands = registry.available_commands
+        return unless args.empty? || !commands.include?(args[0])
+
+        print_usage(commands)
+        exit 1
+      end
+
+      # Build option parser for a command
+      # @param cmd [String] Command name
+      # @param command_config [Hash] Command configuration
+      # @return [OptionBuilder] Configured option builder
+      def build_option_parser(cmd, command_config)
         options = command_config[:default_options].dup
         required_keys = command_config[:required_keys]
 
@@ -50,114 +74,40 @@ module EpubTools
                                .with_banner("Usage: #{program_name} #{cmd} [options]")
                                .with_help_option
 
-        # Configure command-specific options
-        configure_command_options(cmd, builder)
+        @options_configurator.configure(cmd, builder)
+        builder
+      end
 
-        # Parse arguments and run the command
+      # Execute a command with parsed options
+      # @param command_config [Hash] Command configuration
+      # @param builder [OptionBuilder] Option builder instance
+      # @param args [Array<String>] Command line arguments
+      # @return [Object] Command instance
+      def execute_command(command_config, builder, args)
         options = builder.parse(args)
         command_class = command_config[:class]
-        command_class.new(options).run
-        true
+        command_instance = command_class.new(options)
+        command_instance.run
+        command_instance
       end
 
-      private
-
       # Print usage information
       # @param commands [Array<String>] Available commands
       def print_usage(_commands)
-        puts <<~USAGE
-          Usage: #{program_name} 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
+        puts "Usage: #{program_name} COMMAND [options]"
+        puts 'Commands:'
+        print_command_list
       end
 
-      # Configure command-specific options
-      # @param cmd [String] Command name
-      # @param builder [OptionBuilder] Option builder instance
-      def configure_command_options(cmd, builder)
-        case cmd
-        when 'add'
-          builder.with_custom_options do |opts, options|
-            opts.on('-c DIR', '--chapters-dir DIR', 'Chapters directory (required)') { |v| options[:chapters_dir] = v }
-            opts.on('-e DIR', '--oebps-dir DIR', 'EPUB OEBPS directory (required)') do |v|
-              options[:oebps_dir] = v
-            end
-          end
-
-        when 'extract'
-          builder.with_custom_options do |opts, options|
-            opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') do |v|
-              options[:source_dir] = v
-            end
-            opts.on('-t DIR', '--target-dir DIR',
-                    'Directory where the XHTML files will be extracted to (required)') do |v|
-              options[:target_dir] = v
-            end
-          end
-          .with_verbose_option
-
-        when 'split'
-          builder.with_custom_options do |opts, 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)') do |v|
-              options[:book_title] = v
-            end
-            opts.on('-o DIR', '--output-dir DIR',
-                    "Output directory for chapter files (default: #{options[:output_dir]})") do |v|
-              options[:output_dir] = v
-            end
-            opts.on('-p PREFIX', '--prefix PREFIX',
-                    "Filename prefix for chapters (default: #{options[:prefix]})") do |v|
-              options[:prefix] = v
-            end
-          end
-          .with_verbose_option
-
-        when 'init'
-          builder.with_title_option
-                 .with_author_option
-                 .with_custom_options do |opts, options|
-            opts.on('-o DIR', '--output-dir DIR', 'Destination EPUB directory (required)') do |v|
-              options[:destination] = v
-            end
-          end
-            .with_cover_option
-
-        when 'pack'
-          builder.with_input_dir('EPUB directory to package')
-                 .with_output_file('Output EPUB file path')
-                 .with_verbose_option
-
-        when 'unpack'
-          builder.with_custom_options do |opts, options|
-            opts.on('-i FILE', '--input-file FILE', 'EPUB file to unpack (required)') { |v| options[:epub_file] = v }
-            opts.on('-o DIR', '--output-dir DIR', 'Output directory to extract into (default: basename of epub)') do |v|
-              options[:output_dir] = v
-            end
-          end
-          .with_verbose_option
-
-        when 'compile'
-          builder.with_title_option
-                 .with_author_option
-                 .with_custom_options do |opts, options|
-            opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') do |v|
-              options[:source_dir] = v
-            end
-            opts.on('-o FILE', '--output FILE', 'EPUB to create (default: book title in source dir)') do |v|
-              options[:output_file] = v
-            end
-          end
-            .with_cover_option
-            .with_verbose_option
-        end
+      def print_command_list
+        puts '  init      Initialize a bare-bones EPUB'
+        puts '  extract   Extract XHTML files from EPUBs'
+        puts '  split     Split XHTML into separate XHTMLs per chapter'
+        puts '  add       Add chapter XHTML files into an EPUB'
+        puts '  pack      Package an EPUB directory into a .epub file'
+        puts '  unpack    Unpack an EPUB file into a directory'
+        puts '  compile   Takes EPUBs in a dir and splits, cleans, and compiles into a single EPUB.'
+        puts '  append    Extracts and splits EPUBs from a dir and appends them to an existing EPUB.'
       end
     end
   end