epub_tools 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 815d8970acc779f70f7d86395a3658a296536675539dfcf3e7f9a0e0f2d4153a
-  data.tar.gz: da9131f5868b8e8c438e9f41c526d62a2d9f70a320e8d20fa14ffcf4a487f22c
+  metadata.gz: 67e06b8c37f922205445fb328c172184eb14436d876514e306892e17faf767e2
+  data.tar.gz: b0eb25344c96cca09889bc7854b40f48dca2bc49449583a1259dd7ac30803309
 SHA512:
-  metadata.gz: a7dc1015fc79f4c72edec8fb672622122a3540ef3b8923683777a178d397fff5af4e0b0765f237e748ca7a103b9e4c2c0c0c0902d180fcd9cb87e90c613c862f
-  data.tar.gz: fe60fa02c6a7db816b7aab2f5fe368de1a463fdaaa5aa1892146281362ea2cda49d904da541b67e34b2329225e01d9fcc7cd9a3a4c15503cb06cf3d6a10e26ec
+  metadata.gz: b36393dbb0fcc6888a10a2bdb93d30fe88eb423034aacc7455bdb8338e4a0fccdfc8fac70b9998ccd66c1758956afcef0bd8ecd404aabe5eacfa4326b5f3b847
+  data.tar.gz: f9b2071dc6a832b178fa77c8982f43f645a9ebed4059cd023863cde8ed6220300df1155cfea39ee35455188b2fcd6672abf56f3682a5f46c606891e4e1bb0347

data/.gitignore

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

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/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,7 +1,12 @@
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.3)
+    date (3.4.1)
     docile (1.4.1)
+    json (2.11.3)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
     minitest (5.25.5)
     nokogiri (1.18.8-aarch64-linux-gnu)
       racc (~> 1.4)
@@ -19,8 +24,42 @@ GEM
       racc (~> 1.4)
     nokogiri (1.18.8-x86_64-linux-musl)
       racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    psych (5.2.3)
+      date
+      stringio
     racc (1.8.1)
+    rainbow (3.1.1)
     rake (13.2.1)
+    rdoc (6.13.1)
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    rubocop (1.75.4)
+      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.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-minitest (0.38.0)
+      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)
@@ -28,6 +67,11 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    stringio (3.1.7)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    webrick (1.9.1)
     yard (0.9.37)
 
 PLATFORMS
@@ -44,8 +88,13 @@ 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

data/README.md

@@ -115,6 +115,22 @@ Enable coverage reporting:
 ```bash
 COVERAGE=true bundle exec rake test
 ```
+## 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
+bundle install --with doc
+bundle exec yard doc
+```
 
 ## Contributing
 Pull requests welcome! Please open an issue for major changes.

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[:epub_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

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