tahweel 0.1.0

data/lib/tahweel/cli/file_processor.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Tahweel
+  module CLI
+    # Processes a single file by orchestrating conversion/extraction and writing the output.
+    #
+    # This class acts as the bridge between the CLI inputs and the core library logic.
+    # It determines the file type (PDF or Image), calls the appropriate processing method,
+    # and directs the results to the {Tahweel::Writer}.
+    class FileProcessor
+      # Processes the given file according to the provided options.
+      #
+      # @param file_path [String] The path to the input file.
+      # @param options [Hash] Configuration options.
+      # @option options [String] :output The directory to save output files (defaults to current directory).
+      # @option options [Integer] :dpi DPI for PDF conversion (defaults to 150).
+      # @option options [Symbol] :processor The OCR processor to use (e.g., :google_drive).
+      # @option options [Integer] :page_concurrency Max concurrent operations.
+      # @option options [Array<Symbol>] :formats Output formats (e.g., [:txt, :docx]).
+      # @option options [String] :page_separator Separator string for TXT output.
+      # @option options [String] :base_input_path The base path used to determine relative output structure.
+      # @param &block [Proc] A block that will be yielded with progress info.
+      # @yield [Hash] Progress info: {
+      #   stage: :splitting or :ocr,
+      #   current_page: Integer,
+      #   percentage: Float,
+      #   remaining_pages: Integer
+      # }
+      # @return [void]
+      def self.process(file_path, options, &) = new(file_path, options).process(&)
+
+      # Initializes a new FileProcessor.
+      #
+      # @param file_path [String] The path to the input file.
+      # @param options [Hash] Configuration options (see {.process}).
+      def initialize(file_path, options)
+        @file_path = file_path
+        @options = options
+      end
+
+      # Executes the processing logic.
+      #
+      # 1. Ensures the output directory exists.
+      # 2. Checks if output files already exist to avoid redundant processing.
+      # 3. Detects if the input is a PDF or an image.
+      # 4. Runs the appropriate conversion/extraction pipeline.
+      # 5. Writes the results to the configured formats.
+      #
+      # @param &block [Proc] A block that will be yielded with progress info.
+      # @yield [Hash] Progress info: {
+      #   stage: :splitting or :ocr,
+      #   current_page: Integer,
+      #   percentage: Float,
+      #   remaining_pages: Integer
+      # }
+      # @return [void]
+      def process(&)
+        ensure_output_directory_exists
+
+        return if all_outputs_exist?
+
+        pdf? ? process_pdf(&) : process_image
+      end
+
+      private
+
+      def ensure_output_directory_exists = FileUtils.mkdir_p(output_directory)
+
+      def all_outputs_exist?
+        @options[:formats].all? do |format|
+          extension = Tahweel::Writer.new(format: format).extension
+          File.exist?("#{base_output_path}.#{extension}")
+        end
+      end
+
+      def pdf? = File.extname(@file_path).downcase == ".pdf"
+
+      def process_pdf(&)
+        texts = Tahweel.convert(
+          @file_path,
+          dpi: @options[:dpi],
+          processor: @options[:processor],
+          concurrency: @options.fetch(:page_concurrency, Tahweel::Converter::DEFAULT_CONCURRENCY),
+          &
+        )
+
+        write_output(texts)
+      end
+
+      def process_image = write_output([Tahweel.extract(@file_path, processor: @options[:processor])])
+
+      def write_output(texts)
+        Tahweel::Writer.write(
+          texts,
+          base_output_path,
+          formats: @options[:formats],
+          page_separator: @options[:page_separator]
+        )
+      end
+
+      def base_output_path = File.join(output_directory, File.basename(@file_path, ".*"))
+
+      # Determines the output directory.
+      #
+      # If an output option is provided, it attempts to preserve the directory structure
+      # relative to the `base_input_path`. If `base_input_path` is not provided or
+      # calculation fails, it falls back to the provided output directory.
+      #
+      # If no output option is provided, it defaults to the file's own directory.
+      #
+      # @return [String] The target output directory.
+      def output_directory
+        return File.dirname(@file_path) unless @options[:output]
+
+        if @options[:base_input_path]
+          relative_dir = Pathname.new(File.dirname(@file_path)).relative_path_from(@options[:base_input_path])
+          return File.join(@options[:output], relative_dir) unless relative_dir.to_s == "."
+        end
+
+        @options[:output]
+      end
+    end
+  end
+end

data/lib/tahweel/cli/options.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "etc"
+require "optparse"
+
+module Tahweel
+  module CLI
+    # Parses command-line arguments for the Tahweel CLI.
+    class Options
+      POSITIVE_INTEGER = /\A\+?[1-9]\d*(?:_\d+)*\z/
+
+      # Parses the command-line arguments.
+      #
+      # @param args [Array<String>] The command-line arguments.
+      # @return [Hash] The parsed options.
+      def self.parse(args)
+        options = default_options
+        parser = OptionParser.new { configure_parser(_1, options) }
+        begin
+          parser.parse!(args)
+        rescue OptionParser::ParseError => e
+          abort "Error: #{e.message}"
+        end
+
+        validate_args!(args, parser)
+        options
+      end
+
+      def self.default_options
+        {
+          dpi: 150,
+          processor: :google_drive,
+          page_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
+          file_concurrency: (Etc.nprocessors - 2).clamp(2..),
+          output: nil,
+          formats: %i[txt docx],
+          page_separator: Tahweel::Writers::Txt::PAGE_SEPARATOR
+        }
+      end
+
+      def self.configure_parser(opts, options) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        opts.program_name = "tahweel"
+        opts.version = Tahweel::VERSION
+
+        opts.accept(POSITIVE_INTEGER) do |value|
+          n = Integer(value)
+          raise OptionParser::InvalidArgument, "must be a positive integer" if n < 1
+
+          n
+        end
+
+        opts.on(
+          "-e", "--extensions EXTENSIONS", Array,
+          "Comma-separated list of file extensions to process " \
+          "(default: #{Tahweel::CLI::FileCollector::SUPPORTED_EXTENSIONS.join(", ")})"
+        ) do |value|
+          options[:extensions] = value
+        end
+
+        opts.on("--dpi DPI", POSITIVE_INTEGER, "DPI for PDF to Image conversion (default: #{options[:dpi]})") do |value|
+          options[:dpi] = value
+        end
+
+        opts.on(
+          "-p", "--processor PROCESSOR", Tahweel::Ocr::AVAILABLE_PROCESSORS,
+          "OCR processor to use (default: google_drive). Available: #{Tahweel::Ocr::AVAILABLE_PROCESSORS.join(", ")}"
+        ) do |value|
+          options[:processor] = value
+        end
+
+        opts.on(
+          "-P", "--page-concurrency PAGE_CONCURRENCY", POSITIVE_INTEGER,
+          "Max concurrent OCR operations (default: #{options[:page_concurrency]})"
+        ) do |value|
+          options[:page_concurrency] = value
+        end
+
+        opts.on(
+          "-F", "--file-concurrency FILE_CONCURRENCY", POSITIVE_INTEGER,
+          "Max concurrent files to process (default: CPUs - 2 = #{options[:file_concurrency]})"
+        ) do |value|
+          options[:file_concurrency] = value
+        end
+
+        opts.on(
+          "-f", "--formats FORMATS", Array,
+          "Output formats (comma-separated, default: txt). Available: #{Tahweel::Writer::AVAILABLE_FORMATS.join(", ")}"
+        ) do |value|
+          options[:formats] = value.map(&:to_sym)
+
+          invalid_formats = options[:formats] - Tahweel::Writer::AVAILABLE_FORMATS
+          abort "Error: invalid format(s): #{invalid_formats.join(", ")}" if invalid_formats.any?
+        end
+
+        opts.on(
+          "--page-separator SEPARATOR", String,
+          "Separator between pages in TXT output (default: #{options[:page_separator].gsub("\n", "\\n")})"
+        ) do |value|
+          options[:page_separator] = value.gsub("\\n", "\n")
+        end
+
+        opts.on("-o", "--output DIR", String, "Output directory (default: current directory)") do |value|
+          options[:output] = value
+        end
+      end
+
+      def self.validate_args!(args, parser)
+        return unless args.empty?
+
+        puts parser
+        exit 1
+      end
+    end
+  end
+end

data/lib/tahweel/cli/progress_renderer.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Tahweel
+  module CLI
+    # Handles thread-safe rendering of the progress dashboard for the CLI.
+    #
+    # This class manages ANSI escape codes to create a dynamic, multi-line progress display
+    # showing global status and individual worker threads.
+    class ProgressRenderer
+      # ANSI Color Codes
+      RESET = "\e[0m"
+      BOLD = "\e[1m"
+      RED = "\e[31m"
+      GREEN = "\e[32m"
+      YELLOW = "\e[33m"
+      BLUE = "\e[34m"
+      CYAN = "\e[36m"
+      DIM = "\e[2m"
+
+      # Initializes the renderer and prepares the terminal.
+      #
+      # @param total_files [Integer] Total number of files to process.
+      # @param concurrency [Integer] Number of concurrent worker threads.
+      def initialize(total_files, concurrency) # rubocop:disable Metrics/MethodLength
+        @total_files = total_files
+        @concurrency = concurrency
+        @processed_files = 0
+        @worker_states = Array.new(concurrency)
+        @mutex = Mutex.new
+        @start_time = Time.now
+        @running = true
+
+        # Hide cursor
+        $stdout.print "\e[?25l"
+
+        # Reserve space for global status + 1 line per worker
+        $stdout.print "\n" * (@concurrency + 1)
+
+        # Trap Interrupt to restore cursor
+        trap("INT") do
+          @running = false
+          $stdout.print "\e[?25h"
+          exit
+        end
+
+        start_ticker
+      end
+
+      # Updates the state for a worker starting a new file.
+      #
+      # @param worker_index [Integer] The index of the worker thread (0-based).
+      # @param file [String] The path of the file being started.
+      def start_file(worker_index, file)
+        @mutex.synchronize do
+          @worker_states[worker_index] = {
+            file:,
+            stage: "Starting...",
+            percentage: 0,
+            details: ""
+          }
+        end
+      end
+
+      # Updates the progress for a specific worker.
+      #
+      # @param worker_index [Integer] The index of the worker thread.
+      # @param progress [Hash] The progress hash containing stage, percentage, etc.
+      def update(worker_index, progress)
+        @mutex.synchronize do
+          return unless @worker_states[worker_index]
+
+          stage = progress[:stage].to_s.capitalize
+          percentage = progress[:percentage]
+          current_page = progress[:current_page]
+          total_pages = current_page + progress[:remaining_pages]
+
+          @worker_states[worker_index][:stage] = stage
+          @worker_states[worker_index][:percentage] = percentage
+          @worker_states[worker_index][:details] = "(#{current_page}/#{total_pages})"
+        end
+      end
+
+      # Marks a worker as finished with its current file.
+      #
+      # @param worker_index [Integer] The index of the worker thread.
+      def finish_file(worker_index)
+        @mutex.synchronize do
+          @processed_files += 1
+          @worker_states[worker_index] = nil # Idle
+        end
+      end
+
+      # Restores the cursor and finalizes the display.
+      def finish_all
+        @running = false
+        @ticker_thread&.join
+        render # Ensure final state is drawn
+        $stdout.print "\e[?25h"
+      end
+
+      private
+
+      def start_ticker
+        @ticker_thread = Thread.new do
+          while @running
+            sleep 0.1
+            @mutex.synchronize { render } if @running
+          end
+        end
+      end
+
+      def render # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+        # Move cursor up to the start of our block
+        $stdout.print "\e[#{@concurrency + 1}A"
+
+        # 1. Global Progress
+        percent = @total_files.positive? ? ((@processed_files.to_f / @total_files) * 100).round(1) : 0
+        elapsed = (Time.now - @start_time).round
+        $stdout.print "\r\e[K" # Clear line
+        puts "#{BOLD}Total Progress:#{RESET} [#{GREEN}#{@processed_files}#{RESET}/#{@total_files}] #{CYAN}#{percent}%#{RESET} | Time: #{YELLOW}#{elapsed}s#{RESET}" # rubocop:disable Layout/LineLength
+
+        # 2. Worker Statuses
+        @concurrency.times do |i|
+          $stdout.print "\r\e[K" # Clear line
+          state = @worker_states[i]
+          if state
+            # Limit filename length to avoid wrapping issues, truncate from beginning
+            fname = truncate_path(state[:file], 40)
+            stage_color = state[:stage] == "Splitting" ? BLUE : YELLOW
+            puts " [Worker #{i + 1}] #{CYAN}#{fname}#{RESET} | #{stage_color}#{state[:stage].ljust(10)}#{RESET} | #{GREEN}#{state[:percentage].to_s.rjust(5)}%#{RESET} #{DIM}#{state[:details]}#{RESET}" # rubocop:disable Layout/LineLength
+          else
+            puts " [Worker #{i + 1}] #{DIM}Idle#{RESET}"
+          end
+        end
+
+        $stdout.flush
+      end
+
+      def truncate_path(path, max_length)
+        return path.ljust(max_length) if path.length <= max_length
+
+        "...#{path[-(max_length - 3)..]}"
+      end
+    end
+  end
+end

data/lib/tahweel/converter.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "pdf_splitter"
+require_relative "ocr"
+require "fileutils"
+
+module Tahweel
+  # Orchestrates the full conversion process:
+  # 1. Splits a PDF into images.
+  # 2. Performs OCR on each image concurrently.
+  # 3. Returns the aggregated text.
+  # 4. Cleans up temporary files.
+  class Converter
+    # Max concurrent OCR operations to avoid hitting API rate limits too hard.
+    DEFAULT_CONCURRENCY = 12
+
+    # Convenience method to convert a PDF file to text.
+    #
+    # @param pdf_path [String] Path to the PDF file.
+    # @param dpi [Integer] DPI for PDF to image conversion (default: 150).
+    # @param processor [Symbol] OCR processor to use (default: :google_drive).
+    # @param concurrency [Integer] Max concurrent OCR operations (default: 12).
+    # @param &block [Proc] A block that will be yielded with progress info.
+    # @yield [Hash] Progress info: {
+    #   stage: :splitting or :ocr,
+    #   current_page: Integer,
+    #   percentage: Float,
+    #   remaining_pages: Integer
+    # }
+    # @return [Array<String>] An array containing the text of each page.
+    def self.convert(
+      pdf_path,
+      dpi: PdfSplitter::DEFAULT_DPI,
+      processor: :google_drive,
+      concurrency: DEFAULT_CONCURRENCY,
+      &
+    ) = new(pdf_path, dpi:, processor:, concurrency:).convert(&)
+
+    # Initializes the Converter.
+    #
+    # @param pdf_path [String] Path to the PDF file.
+    # @param dpi [Integer] DPI for PDF to image conversion.
+    # @param processor [Symbol] OCR processor to use.
+    # @param concurrency [Integer] Max concurrent OCR operations.
+    def initialize(pdf_path, dpi: PdfSplitter::DEFAULT_DPI, processor: :google_drive, concurrency: DEFAULT_CONCURRENCY)
+      @pdf_path = pdf_path
+      @dpi = dpi
+      @processor_type = processor
+      @concurrency = concurrency
+    end
+
+    # Executes the conversion process.
+    #
+    # @param &block [Proc] A block that will be yielded with progress info.
+    # @yield [Hash] Progress info: {
+    #   stage: :splitting or :ocr,
+    #   current_page: Integer,
+    #   percentage: Float,
+    #   remaining_pages: Integer
+    # }
+    # @return [Array<String>] An array containing the text of each page.
+    def convert(&)
+      image_paths, temp_dir = PdfSplitter.split(@pdf_path, dpi: @dpi, &).values_at(:image_paths, :folder_path)
+
+      begin
+        process_images(image_paths, Ocr.new(processor: @processor_type), &)
+      ensure
+        FileUtils.rm_rf(temp_dir)
+      end
+    end
+
+    private
+
+    def process_images(image_paths, ocr_engine, &)
+      texts = Array.new(image_paths.size)
+      mutex = Mutex.new
+      processed_count = 0
+
+      run_workers(build_queue(image_paths), ocr_engine, texts, mutex) do
+        processed_count += 1
+        report_progress(processed_count, image_paths.size, &)
+      end
+
+      texts
+    end
+
+    def build_queue(image_paths)
+      queue = Queue.new
+      image_paths.each_with_index { |path, index| queue << [path, index] }
+      queue
+    end
+
+    def run_workers(queue, ocr_engine, texts, mutex, &)
+      Array.new(@concurrency) do
+        Thread.new { process_queue_items(queue, ocr_engine, texts, mutex, &) }
+      end.each(&:join)
+    end
+
+    def process_queue_items(queue, ocr_engine, texts, mutex, &)
+      loop do
+        begin
+          path, index = queue.pop(true)
+        rescue ThreadError
+          break
+        end
+
+        text = ocr_engine.extract(path)
+        save_result(texts, index, text, mutex, &)
+      end
+    end
+
+    def save_result(texts, index, text, mutex)
+      mutex.synchronize do
+        texts[index] = text
+        yield
+      end
+    end
+
+    def report_progress(processed, total)
+      return unless block_given?
+
+      yield({
+        file_path: @pdf_path,
+        stage: :ocr,
+        current_page: processed,
+        percentage: ((processed.to_f / total) * 100).round(2),
+        remaining_pages: total - processed
+      })
+    end
+  end
+end

data/lib/tahweel/ocr.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "processors/google_drive"
+
+module Tahweel
+  # The main entry point for Optical Character Recognition (OCR).
+  # This class acts as a factory/strategy context, delegating the actual extraction logic
+  # to a specific processor.
+  #
+  # @example Usage with default processor (Google Drive)
+  #   text = Tahweel::Ocr.extract("image.png")
+  #
+  # @example Usage with a specific processor (Future-proofing)
+  #   # text = Tahweel::Ocr.extract("image.png", processor: :tesseract)
+  class Ocr
+    AVAILABLE_PROCESSORS = [:google_drive].freeze
+
+    # Convenience method to extract text using a specific processor.
+    #
+    # @param file_path [String] Path to the image file.
+    # @param processor [Symbol] The processor to use (default: :google_drive).
+    # @return [String] The extracted text.
+    def self.extract(file_path, processor: :google_drive) = new(processor: processor).extract(file_path)
+
+    # Initializes the OCR engine with a specific processor strategy.
+    #
+    # @param processor [Symbol] The processor to use (default: :google_drive).
+    # @raise [ArgumentError] If an unknown processor is specified.
+    def initialize(processor: :google_drive)
+      @processor = case processor
+                   when :google_drive then Processors::GoogleDrive.new
+                   else raise ArgumentError, "Unknown processor: #{processor}"
+                   end
+    end
+
+    # Extracts text from the file using the configured processor.
+    #
+    # @param file_path [String] Path to the image file.
+    # @return [String] The extracted text.
+    def extract(file_path) = @processor.extract(file_path)
+  end
+end