epub_tools 0.3.0 → 0.4.0

data/lib/epub_tools/cli/option_builder.rb

@@ -0,0 +1,164 @@
+require 'optparse'
+
+module EpubTools
+  module CLI
+    # Builds and manages command line options
+    class OptionBuilder
+      attr_reader :options, :required_keys, :parser
+
+      # Initialize a new OptionBuilder
+      # @param default_options [Hash] Default options to start with
+      # @param required_keys [Array<Symbol>] Keys that must be present in the final options
+      def initialize(default_options = {}, required_keys = [])
+        @options = default_options.dup
+        @required_keys = required_keys
+        @parser = OptionParser.new
+      end
+
+      # Add banner to the option parser
+      # @param text [String] Banner text
+      # @return [self] for method chaining
+      def with_banner(text)
+        @parser.banner = text
+        self
+      end
+
+      # Add help option to the parser
+      # @return [self] for method chaining
+      def with_help_option
+        @parser.on('-h', '--help', 'Print this help') do
+          puts @parser
+          exit
+        end
+        self
+      end
+
+      # Add verbose option to the parser
+      # @return [self] for method chaining
+      def with_verbose_option
+        @options[:verbose] = true unless @options.key?(:verbose)
+        @parser.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| @options[:verbose] = !v }
+        self
+      end
+
+      # Add input file option to the parser
+      # @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)
+        desc = required ? "#{description} (required)" : description
+        @parser.on('-i FILE', '--input-file FILE', desc) { |v| @options[:input_file] = v }
+        self
+      end
+
+      # Add input directory option to the parser
+      # @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)
+        desc = required ? "#{description} (required)" : description
+        @parser.on('-i DIR', '--input-dir DIR', desc) { |v| @options[:input_dir] = v }
+        self
+      end
+
+      # Add output directory option to the parser
+      # @param description [String] Option description
+      # @param default [String, nil] Default value
+      # @return [self] for method chaining
+      def with_output_dir(description = 'Output directory', default = nil)
+        if default
+          desc = "#{description} (default: #{default})"
+          @options[:output_dir] = default unless @options.key?(:output_dir)
+        else
+          desc = "#{description} (required)"
+        end
+        @parser.on('-o DIR', '--output-dir DIR', desc) { |v| @options[:output_dir] = v }
+        self
+      end
+
+      # Add output file option to the parser
+      # @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)
+        desc = required ? "#{description} (required)" : description
+        @parser.on('-o FILE', '--output-file FILE', desc) { |v| @options[:output_file] = v }
+        self
+      end
+
+      # Add title option to the parser
+      # @return [self] for method chaining
+      def with_title_option
+        @parser.on('-t TITLE', '--title TITLE', 'Book title (required)') { |v| @options[:title] = v }
+        self
+      end
+
+      # Add author option to the parser
+      # @return [self] for method chaining
+      def with_author_option
+        @parser.on('-a AUTHOR', '--author AUTHOR', 'Author name (required)') { |v| @options[:author] = v }
+        self
+      end
+
+      # Add cover option to the parser
+      # @return [self] for method chaining
+      def with_cover_option
+        @parser.on('-c PATH', '--cover PATH', 'Cover image file path (optional)') { |v| @options[:cover_image] = v }
+        self
+      end
+
+      # Add a custom option to the parser
+      # @param short [String] Short option flag
+      # @param long [String] Long option flag
+      # @param description [String] Option description
+      # @param option_key [Symbol] Key in the options hash
+      # @param block [Proc] Optional block for custom processing
+      # @return [self] for method chaining
+      def with_option(short, long, description, option_key)
+        @parser.on(short, long, description) do |v|
+          @options[option_key] = block_given? ? yield(v) : v
+        end
+        self
+      end
+
+      # Add a custom block to configure options
+      # @yield [OptionParser, Hash] Yields the parser and options hash
+      # @return [self] for method chaining
+      def with_custom_options
+        yield @parser, @options if block_given?
+        self
+      end
+
+      # Parse the command line arguments
+      # @param args [Array<String>] Command line arguments
+      # @return [Hash] Parsed options
+      # @raise [SystemExit] If required options are missing
+      def parse(args = ARGV)
+        begin
+          @parser.parse!(args.dup)
+          validate_required_keys
+        rescue ArgumentError => e
+          abort "#{e.message}\n#{@parser}"
+        end
+        @options
+      end
+
+      private
+
+      # Validate that all required keys are present in the options
+      # @raise [SystemExit] If required options are missing
+      def validate_required_keys
+        return if @required_keys.empty?
+
+        missing = @required_keys.select { |k| @options[k].nil? }
+        return if missing.empty?
+
+        raise ArgumentError, "Missing required options: #{missing_keys(missing)}"
+      end
+
+      def missing_keys(keys)
+        keys.map { |k| "--#{k.to_s.tr('_', '-')}" }.join(', ')
+      end
+    end
+  end
+end

data/lib/epub_tools/cli/runner.rb

@@ -0,0 +1,164 @@
+require_relative 'command_registry'
+require_relative 'option_builder'
+
+module EpubTools
+  module CLI
+    # Main runner for the CLI application
+    class Runner
+      attr_reader :registry, :program_name
+
+      # Initialize a new CLI Runner
+      # @param program_name [String] Name of the program
+      def initialize(program_name = nil)
+        @registry = CommandRegistry.new
+        @program_name = program_name || File.basename($PROGRAM_NAME)
+      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
+
+        cmd = args.shift
+        handle_command(cmd, args)
+      end
+
+      # Handle a specific command
+      # @param cmd [String] Command name
+      # @param args [Array<String>] Command line arguments
+      # @return [Boolean] true if the command was run successfully
+      def handle_command(cmd, args = ARGV)
+        command_config = registry.get(cmd)
+        return false unless command_config
+
+        options = command_config[:default_options].dup
+        required_keys = command_config[:required_keys]
+
+        builder = OptionBuilder.new(options, required_keys)
+                               .with_banner("Usage: #{program_name} #{cmd} [options]")
+                               .with_help_option
+
+        # Configure command-specific options
+        configure_command_options(cmd, builder)
+
+        # Parse arguments and run the command
+        options = builder.parse(args)
+        command_class = command_config[:class]
+        command_class.new(options).run
+        true
+      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
+      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', '--epub-oebps-dir DIR', 'EPUB OEBPS directory (required)') do |v|
+              options[:epub_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
+      end
+    end
+  end
+end

data/lib/epub_tools/cli.rb

@@ -0,0 +1,45 @@
+require_relative 'cli/command_registry'
+require_relative 'cli/option_builder'
+require_relative 'cli/runner'
+
+module EpubTools
+  # CLI module - houses the object-oriented command line interface components
+  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.register('add', EpubTools::AddChapters,
+                               %i[chapters_dir epub_oebps_dir])
+
+      runner.registry.register('extract', EpubTools::XHTMLExtractor,
+                               %i[source_dir target_dir],
+                               { verbose: true })
+
+      runner.registry.register('split', EpubTools::SplitChapters,
+                               %i[input_file book_title],
+                               { output_dir: './chapters', prefix: 'chapter', verbose: true })
+
+      runner.registry.register('init', EpubTools::EpubInitializer,
+                               %i[title author destination],
+                               { verbose: true })
+
+      runner.registry.register('pack', EpubTools::PackEbook,
+                               %i[input_dir output_file],
+                               { verbose: true })
+
+      runner.registry.register('unpack', EpubTools::UnpackEbook,
+                               [:epub_file],
+                               { verbose: true })
+
+      runner.registry.register('compile', EpubTools::CompileBook,
+                               %i[title author source_dir],
+                               { verbose: true })
+
+      runner
+    end
+  end
+end

data/lib/epub_tools/compile_book.rb

@@ -1,27 +1,48 @@
 #!/usr/bin/env ruby
 require 'fileutils'
+require_relative 'loggable'
 require_relative 'xhtml_extractor'
 require_relative 'split_chapters'
 require_relative 'epub_initializer'
-require_relative 'add_chapters_to_epub'
+require_relative 'add_chapters'
 require_relative 'pack_ebook'
 
 module EpubTools
   # Orchestrates extraction, splitting, validation, and packaging of book EPUBs
   class CompileBook
-    attr_reader :title, :author, :source_dir, :cover_image, :output_file, :build_dir, :verbose
-
-    # title: String, author: String, source_dir: path to input epubs
-    # cover_image: optional path to cover image, output_file: filename for final epub
-    # build_dir: optional working directory for intermediate files
-    def initialize(title:, author:, source_dir:, cover_image: nil, output_file: nil, build_dir: nil, verbose: false)
-      @title       = title
-      @author      = author
-      @source_dir  = source_dir
-      @cover_image = cover_image
-      @output_file = output_file || default_output_file
-      @build_dir   = build_dir || File.join(Dir.pwd, '.epub_tools_build')
-      @verbose     = verbose
+    include Loggable
+    # 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 = {})
+      @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
     end
 
     # Run the full compile workflow
@@ -40,10 +61,6 @@ module EpubTools
 
     private
 
-    def log(message)
-      puts message if verbose
-    end
-
     def default_output_file
       "#{title.gsub(' ', '_')}.epub"
     end
@@ -54,7 +71,7 @@ module EpubTools
     end
 
     def prepare_dirs
-      log "Preparing build directories..."
+      log 'Preparing build directories...'
       FileUtils.mkdir_p(xhtml_dir)
       FileUtils.mkdir_p(chapters_dir)
     end
@@ -73,52 +90,78 @@ module EpubTools
 
     def extract_xhtmls
       log "Extracting XHTML files from epubs in '#{source_dir}'..."
-      XHTMLExtractor.new(source_dir: source_dir, target_dir: xhtml_dir, verbose: verbose).extract_all
+      XHTMLExtractor.new({
+                           source_dir: source_dir,
+                           target_dir: xhtml_dir,
+                           verbose: verbose
+                         }).run
     end
 
     def split_xhtmls
-      log "Splitting XHTML files into chapters..."
+      log 'Splitting XHTML files into chapters...'
       Dir.glob(File.join(xhtml_dir, '*.xhtml')).each do |xhtml_file|
         base = File.basename(xhtml_file, '.xhtml')
         log "Splitting '#{base}'..."
-        SplitChapters.new(xhtml_file, title, chapters_dir, 'chapter', verbose).run
+        SplitChapters.new({
+                            input_file: xhtml_file,
+                            book_title: title,
+                            output_dir: chapters_dir,
+                            output_prefix: 'chapter',
+                            verbose: verbose
+                          }).run
       end
     end
 
     def validate_sequence
-      log "Validating chapter sequence..."
+      log 'Validating chapter sequence...'
       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
       raise "No chapter files found in #{chapters_dir}" if nums.empty?
+
       sorted = nums.sort.uniq
       missing = (sorted.first..sorted.last).to_a - sorted
-      if missing.any?
-        raise "Missing chapter numbers: #{missing.join(' ')}"
-      else
-        log "Chapter sequence is complete: #{sorted.first} to #{sorted.last}."
-      end
+      raise "Missing chapter numbers: #{missing.join(' ')}" if missing.any?
+
+      log "Chapter sequence is complete: #{sorted.first} to #{sorted.last}."
     end
 
     def initialize_epub
-      log "Initializing new EPUB..."
+      log 'Initializing new EPUB...'
       if cover_image
-        EpubInitializer.new(title, author, epub_dir, cover_image).run
+        EpubInitializer.new({
+                              title: title,
+                              author: author,
+                              destination: epub_dir,
+                              cover_image: cover_image
+                            }).run
       else
-        EpubInitializer.new(title, author, epub_dir).run
+        EpubInitializer.new({
+                              title: title,
+                              author: author,
+                              destination: epub_dir
+                            }).run
       end
     end
 
     def add_chapters
-      log "Adding chapters to EPUB..."
-      AddChaptersToEpub.new(chapters_dir, File.join(epub_dir, 'OEBPS'), verbose).run
+      log 'Adding chapters to EPUB...'
+      AddChapters.new({
+                        chapters_dir: chapters_dir,
+                        epub_dir: File.join(epub_dir, 'OEBPS'),
+                        verbose: verbose
+                      }).run
     end
 
     def pack_epub
       log "Building final EPUB '#{output_file}'..."
-      PackEbook.new(epub_dir, output_file, verbose: verbose).run
+      PackEbook.new({
+                      input_dir: epub_dir,
+                      output_file: output_file,
+                      verbose: verbose
+                    }).run
     end
   end
 end

data/lib/epub_tools/epub_initializer.rb

@@ -2,22 +2,39 @@
 require 'fileutils'
 require 'time'
 require 'securerandom'
+require_relative 'loggable'
 
 module EpubTools
+  # Sets up a basic empty EPUB directory structure with the basic files created:
+  # - +mimetype+
+  # - +container.xml+
+  # - +title.xhtml+ as a title page
+  # - +package.opf+
+  # - +nav.xhtml+ as a table of contents
+  # - +style.css+ a basic style inherited from the repo
+  # - cover image (optionally)
   class EpubInitializer
-    # title: book title; author: author name; destination: output EPUB directory
-    # cover_image: optional path to cover image file
-    def initialize(title, author, destination, cover_image = nil)
-      @title = title
-      @author = author
-      @destination = File.expand_path(destination)
+    include Loggable
+    # 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] :destination Target directory for the EPUB files (required)
+    # @option options [String] :cover_image Optional path to the cover image
+    # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
+    def initialize(options = {})
+      @title = options.fetch(:title)
+      @author = options.fetch(:author)
+      @destination = File.expand_path(options.fetch(:destination))
       @uuid = "urn:uuid:#{SecureRandom.uuid}"
       @modified = Time.now.utc.iso8601
-      @cover_image_path = cover_image
+      @cover_image_path = options[:cover_image]
       @cover_image_fname = nil
       @cover_image_media_type = nil
+      @verbose = options[:verbose] || false
     end
 
+    # Creates the empty ebook and returns the directory
     def run
       create_structure
       write_mimetype
@@ -27,6 +44,8 @@ module EpubTools
       write_package_opf
       write_nav
       write_style
+      log "Created empty ebook structure at: #{@destination}"
+      @destination
     end
 
     private
@@ -37,7 +56,7 @@ module EpubTools
     end
 
     def write_mimetype
-      File.write("#{@destination}/mimetype", "application/epub+zip")
+      File.write("#{@destination}/mimetype", 'application/epub+zip')
     end
 
     def write_title_page
@@ -114,36 +133,39 @@ module EpubTools
       File.write(File.join(@destination, 'OEBPS', 'cover.xhtml'), content)
     end
 
+    def mitem(id, href, type, properties = nil)
+      xml = "<item id=\"#{id}\" href=\"#{href}\" media-type=\"#{type}\""
+      xml += " properties=\"#{properties}\"" if properties
+      "#{xml}/>"
+    end
+
     # Generates the package.opf with optional cover image entries
     def write_package_opf
       manifest_items = []
       spine_items = []
-
-      manifest_items << '<item id="style" href="style.css" media-type="text/css"/>'
-      manifest_items << '<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>'
+      manifest_items << mitem('style', 'style.css', 'text/css')
+      manifest_items << mitem('nav', 'nav.xhtml', 'application/xhtml+xml', 'nav')
 
       if @cover_image_fname
-        manifest_items << %Q{<item id="cover-image" href="#{@cover_image_fname}" media-type="#{@cover_image_media_type}" properties="cover-image"/>}
-        manifest_items << '<item id="cover-page" href="cover.xhtml" media-type="application/xhtml+xml"/>'
+        manifest_items << mitem('cover-image', @cover_image_fname, @cover_image_media_type, 'cover-image')
+        manifest_items << mitem('cover-page', 'cover.xhtml', 'application/xhtml+xml')
         spine_items << '<itemref idref="cover-page"/>'
       end
 
-      manifest_items << '<item id="title" href="title.xhtml" media-type="application/xhtml+xml"/>'
+      manifest_items << mitem('title', 'title.xhtml', 'application/xhtml+xml')
       spine_items << '<itemref idref="title"/>'
 
       metadata = []
-      metadata << %Q{<dc:identifier id="pub-id">#{@uuid}</dc:identifier>}
-      metadata << %Q{<dc:title>#{@title}</dc:title>}
-      metadata << %Q{<dc:creator>#{@author}</dc:creator>}
-      metadata << "<dc:language>en</dc:language>"
-      metadata << %Q{<meta property="dcterms:modified">#{@modified}</meta>}
-      metadata << %Q{<meta property="schema:accessMode">textual</meta>}
-      metadata << %Q{<meta property="schema:accessibilityFeature">unknown</meta>}
-      metadata << %Q{<meta property="schema:accessibilityHazard">none</meta>}
-      metadata << %Q{<meta property="schema:accessModeSufficient">textual</meta>}
-      if @cover_image_fname
-        metadata << %Q{<meta name="cover" content="cover-image"/>}
-      end
+      metadata << %(<dc:identifier id="pub-id">#{@uuid}</dc:identifier>)
+      metadata << %(<dc:title>#{@title}</dc:title>)
+      metadata << %(<dc:creator>#{@author}</dc:creator>)
+      metadata << '<dc:language>en</dc:language>'
+      metadata << %(<meta property="dcterms:modified">#{@modified}</meta>)
+      metadata << %(<meta property="schema:accessMode">textual</meta>)
+      metadata << %(<meta property="schema:accessibilityFeature">unknown</meta>)
+      metadata << %(<meta property="schema:accessibilityHazard">none</meta>)
+      metadata << %(<meta property="schema:accessModeSufficient">textual</meta>)
+      metadata << %(<meta name="cover" content="cover-image"/>) if @cover_image_fname
 
       content = <<~XML
         <?xml version="1.0" encoding="utf-8"?>