tahweel 0.1.1 → 0.1.3

data/lib/tahweel/pdf_splitter.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
+require "etc"
 require "fileutils"
-require "rbconfig"
 require "securerandom"
 require "tmpdir"
-require "vips"
+
+require_relative "poppler_installer"
 
 module Tahweel
   # Handles the logic for splitting a PDF file into individual image pages.
-  # Uses the libvips library for high-performance image processing.
+  # Uses Poppler utils (pdftoppm, pdfinfo) for high-performance image processing.
   class PdfSplitter
     # Default DPI used when converting PDF pages to images.
     # 150 DPI is a good balance between quality and file size for general documents.
@@ -25,7 +26,7 @@ module Tahweel
     #   percentage: Float,
     #   remaining_pages: Integer
     # }
-    # @return [Hash] A hash containing the :folder_path (String) and :image_paths (Array<String>).
+    # @return [Hash] A hash containing the :folder_path (String) and :images_paths (Array<String>).
     def self.split(pdf_path, dpi: DEFAULT_DPI, &) = new(pdf_path, dpi:).split(&)
 
     # Initializes a new PdfSplitter instance.
@@ -35,13 +36,12 @@ module Tahweel
     def initialize(pdf_path, dpi: DEFAULT_DPI)
       @pdf_path = pdf_path
       @dpi = dpi
-      @image_paths = []
     end
 
     # Executes the PDF splitting process.
     #
     # This method performs the following steps:
-    # 1. Checks if libvips is installed (skips on Windows).
+    # 1. Checks if Poppler utils are available (installs if missing on Windows).
     # 2. Validates the existence of the source PDF file.
     # 3. Creates a unique temporary directory for output.
     # 4. Iterates through each page of the PDF and converts it to a PNG image.
@@ -55,12 +55,11 @@ module Tahweel
     # }
     # @return [Hash] Result hash with keys:
     #   - :folder_path [String] The absolute path to the temporary directory containing the images.
-    #   - :image_paths [Array<String>] List of absolute paths for each generated image file.
-    # @raise [RuntimeError] If the PDF file is not found or libvips is missing.
-    # @raise [Vips::Error] If the underlying VIPS library encounters an error during processing.
+    #   - :images_paths [Array<String>] List of absolute paths for each generated image file.
+    # @raise [RuntimeError] If the PDF file is not found.
     def split(&)
-      check_libvips_installed!
       validate_file_exists!
+      PopplerInstaller.ensure_installed!
       setup_output_directory
       process_pages(&)
       result
@@ -68,20 +67,7 @@ module Tahweel
 
     private
 
-    attr_reader :pdf_path, :dpi, :image_paths, :output_dir
-
-    # Checks if the `vips` CLI tool is available in the system PATH.
-    # Skips this check on Windows systems, assuming the environment is managed differently.
-    # Aborts execution with an error message if vips is missing.
-    def check_libvips_installed!
-      return if /mswin|mingw|cygwin/.match?(RbConfig::CONFIG["host_os"])
-      return if system("vips --version", out: File::NULL, err: File::NULL)
-
-      abort "Error: libvips is not installed. Please install it before using Tahweel.\n" \
-            "MacOS: `brew install vips`\n" \
-            "Ubuntu: `sudo apt install libvips42`\n" \
-            "Windows: Already installed with the Tahweel gem"
-    end
+    attr_reader :pdf_path, :dpi, :output_dir
 
     # Ensures the source PDF file actually exists.
     # @raise [RuntimeError] if the file is missing.
@@ -106,33 +92,101 @@ module Tahweel
     # }
     # @return [void]
     def process_pages(&)
-      total_pages.times do |i|
-        extract_page(i)
+      mutex = Mutex.new
+      processed_count = 0
+
+      run_workers(build_queue, mutex) do
+        processed_count += 1
+        report_progress(processed_count, &)
+      end
+    end
+
+    # Builds a queue containing all page indices to be processed.
+    # @return [Queue] The queue populated with page numbers.
+    def build_queue
+      queue = Queue.new
+      total_pages.times { queue << _1 }
+      queue
+    end
 
-        next unless block_given?
+    # Spawns and manages worker threads to process the queue.
+    #
+    # @param queue [Queue] The queue of pages to process.
+    # @param mutex [Mutex] Synchronization primitive for thread safety.
+    # @param &block [Proc] Block to execute when a page is processed.
+    def run_workers(queue, mutex, &)
+      concurrency = (Etc.nprocessors - 2).clamp(2..)
+
+      Array.new([concurrency, total_pages].min) do
+        Thread.new { process_queue_items(queue, mutex, &) }
+      end.each(&:join)
+    end
 
-        yield({
-          file_path: @pdf_path, stage: :splitting,
-          current_page: i + 1,
-          percentage: (((i + 1).to_f / total_pages) * 100).round(2),
-          remaining_pages: total_pages - (i + 1)
-        })
+    # Processing loop for individual worker threads.
+    #
+    # @param queue [Queue] The shared queue of pages.
+    # @param mutex [Mutex] Synchronization primitive.
+    # @param &block [Proc] Block to yield for progress updates.
+    def process_queue_items(queue, mutex, &)
+      loop do
+        begin
+          page_num = queue.pop(true)
+        rescue ThreadError
+          break
+        end
+
+        extract_page(page_num)
+
+        mutex.synchronize(&)
       end
     end
 
+    # Reports progress back to the caller.
+    #
+    # @param processed [Integer] Number of pages processed so far.
+    # @param &block [Proc] The progress callback block.
+    def report_progress(processed, &)
+      return unless block_given?
+
+      yield({
+        file_path: @pdf_path, stage: :splitting,
+        current_page: processed,
+        percentage: ((processed.to_f / total_pages) * 100).round(2),
+        remaining_pages: total_pages - processed
+      })
+    end
+
     # Calculates the total number of pages in the PDF by loading the first page metadata.
     # @return [Integer] The page count.
     def total_pages
-      @total_pages ||= Vips::Image.pdfload(pdf_path, page: 0, dpi: dpi, access: :sequential).get("pdf-n_pages")
+      @total_pages ||= begin
+        output = `#{PopplerInstaller.pdfinfo_path} "#{pdf_path}"`.encode(
+          "UTF-8",
+          invalid: :replace, undef: :replace, replace: ""
+        )
+
+        pages = output[/Pages:\s*(\d+)/, 1]
+        raise "Failed to get page count from PDF: #{output}" unless pages
+
+        pages.to_i
+      end
     end
 
     # Extracts a specific page from the PDF and saves it as a PNG.
     #
     # @param page_num [Integer] The zero-based index of the page to extract.
     def extract_page(page_num)
-      output_path = File.join(output_dir, "page_#{page_num + 1}.png")
-      Vips::Image.pdfload(pdf_path, page: page_num, dpi: dpi, access: :sequential).write_to_file(output_path)
-      image_paths << output_path
+      output_prefix = File.join(output_dir, "page")
+
+      system(
+        PopplerInstaller.pdftoppm_path,
+        "-png",
+        "-r", dpi.to_s,
+        "-f", (page_num + 1).to_s,
+        "-l", (page_num + 1).to_s,
+        pdf_path,
+        output_prefix
+      )
     end
 
     # Constructs the final result hash.
@@ -140,7 +194,7 @@ module Tahweel
     def result
       {
         folder_path: output_dir,
-        image_paths: image_paths
+        images_paths: Dir.glob(File.join(output_dir, "page-*.png")).sort!
       }
     end
   end

data/lib/tahweel/poppler_installer.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "net/http"
+require "open-uri"
+require "uri"
+
+require "xdg"
+require "zip"
+
+module Tahweel
+  # Handles the installation and path resolution for Poppler utilities.
+  #
+  # On Windows, this class can automatically download and install the necessary
+  # binaries if they are not present. On other platforms, it provides instructions
+  # for manual installation.
+  class PopplerInstaller
+    POPPLER_REPO_API = "https://api.github.com/repos/oschwartz10612/poppler-windows/releases/latest"
+
+    # Ensures that Poppler utilities are installed.
+    #
+    # On Windows: Installs Poppler locally if not found.
+    # On other platforms: Aborts with an error message if Poppler is missing.
+    #
+    # @raise [SystemExit] if Poppler is missing on non-Windows platforms.
+    def self.ensure_installed! # rubocop:disable Metrics/MethodLength
+      installer = new
+      return if installer.installed?
+
+      if Gem.win_platform?
+        installer.install
+      else
+        abort <<~MSG
+          Error: Poppler utilities are not installed. Please install them:
+          MacOS:  `brew install poppler`
+          Ubuntu: `sudo apt install poppler-utils`
+        MSG
+      end
+    end
+
+    # Returns the path to the `pdftoppm` executable.
+    # @return [String] path to the executable.
+    def self.pdftoppm_path = new.pdftoppm_path
+
+    # Returns the path to the `pdfinfo` executable.
+    # @return [String] path to the executable.
+    def self.pdfinfo_path = new.pdfinfo_path
+
+    # Installs Poppler binaries on Windows.
+    #
+    # Downloads the latest release from GitHub and extracts it to the cache directory.
+    # Does nothing if already installed.
+    def install
+      zip_path = nil
+      return if installed?
+
+      zip_path = download_release_file
+      extract_zip_file(zip_path)
+    ensure
+      FileUtils.rm_f(zip_path) if zip_path
+    end
+
+    # Checks if Poppler utilities are available.
+    #
+    # @return [Boolean] true if `pdftoppm` and `pdfinfo` are in the PATH or cached.
+    def installed? = (command_exists?("pdftoppm") && command_exists?("pdfinfo")) || cached?
+
+    # Checks if Poppler binaries are present in the local cache (Windows only).
+    #
+    # @return [Boolean] true if cached binaries exist.
+    def cached?
+      return false unless Gem.win_platform?
+
+      File.exist?(File.join(cached_bin_path, "pdftoppm.exe"))
+    end
+
+    # Resolves the path to the `pdftoppm` executable.
+    #
+    # Prioritizes the system PATH, falling back to the cached version on Windows.
+    #
+    # @return [String] path to `pdftoppm`.
+    def pdftoppm_path
+      return "pdftoppm" if command_exists?("pdftoppm")
+
+      Gem.win_platform? ? File.join(cached_bin_path, "pdftoppm.exe") : nil
+    end
+
+    # Resolves the path to the `pdfinfo` executable.
+    #
+    # Prioritizes the system PATH, falling back to the cached version on Windows.
+    #
+    # @return [String] path to `pdfinfo`.
+    def pdfinfo_path
+      return "pdfinfo" if command_exists?("pdfinfo")
+
+      Gem.win_platform? ? File.join(cached_bin_path, "pdfinfo.exe") : nil
+    end
+
+    private
+
+    # Locates the `bin` directory within the cached Poppler installation.
+    #
+    # Searches for a directory matching "poppler-*" in the cache directory and returns
+    # the path to its `Library/bin` subdirectory.
+    #
+    # @return [String] Path to the `bin` directory, or an empty string if not found.
+    def cached_bin_path
+      poppler_root = Dir.glob(File.join(cache_dir, "poppler-*")).first
+      return "" unless poppler_root
+
+      File.join(poppler_root, "Library", "bin")
+    end
+
+    # Checks if a command is available in the system path.
+    #
+    # @param cmd [String] The command to check for.
+    # @return [Boolean] true if the command exists in the PATH.
+    def command_exists?(cmd)
+      tool = Gem.win_platform? ? "where" : "which"
+      system("#{tool} #{cmd} > #{File::NULL} 2>&1")
+    end
+
+    # Downloads the latest Poppler release zip file.
+    #
+    # Fetches the download URL from the GitHub API and saves the file to the cache directory.
+    #
+    # @return [String] The local path to the downloaded zip file.
+    def download_release_file
+      release_url = latest_release_url
+      zip_path = File.join(cache_dir, File.basename(release_url))
+      URI.parse(release_url).open { File.binwrite(zip_path, _1.read) }
+      zip_path
+    end
+
+    # Retrieves the download URL for the latest Windows release of Poppler.
+    #
+    # Queries the GitHub API for the latest release and finds the asset matching "Release*.zip".
+    #
+    # @return [String] The download URL of the asset.
+    # @raise [SystemExit] if the API request fails or no valid asset is found.
+    def latest_release_url # rubocop:disable Metrics/AbcSize
+      uri = URI(POPPLER_REPO_API)
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "Tahweel-Gem"
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { _1.request(request) }
+
+      unless response.is_a?(Net::HTTPSuccess)
+        abort "Failed to fetch Poppler release info: #{response.code} #{response.message}"
+      end
+
+      asset = JSON.parse(response.body)["assets"].find { _1["name"].match?(/^Release.*\.zip$/) }
+
+      asset ? asset["browser_download_url"] : abort("No valid Windows release found for Poppler.")
+    end
+
+    # Extracts the downloaded zip file to the cache directory.
+    #
+    # @param zip_path [String] Path to the zip file to extract.
+    def extract_zip_file(zip_path)
+      Zip::File.open(zip_path) do |zip_file|
+        zip_file.each do |entry|
+          entry_dest = File.join(cache_dir, entry.name)
+          FileUtils.mkdir_p(File.dirname(entry_dest))
+          zip_file.extract(entry, entry_dest) { true }
+        end
+      end
+    end
+
+    # Resolves the directory used for caching downloaded binaries.
+    #
+    # Uses the XDG cache home directory if available, otherwise defaults to `~/.cache/tahweel/poppler`.
+    #
+    # @return [String] Path to the cache directory.
+    def cache_dir
+      base = XDG.new.cache_home.to_s
+      base = File.join(Dir.home, ".cache") if base.empty?
+
+      dir = File.join(base, "tahweel", "poppler")
+      FileUtils.mkdir_p(dir)
+      dir
+    end
+  end
+end

data/lib/tahweel/processors/google_drive.rb

@@ -43,7 +43,7 @@ module Tahweel
 
         begin
           file_id = upload_file(file_path)
-          download_text(file_id).gsub("\r\n", "\n").gsub("________________", "").strip
+          download_text(file_id).gsub("________________", "").strip
         ensure
           delete_file(file_id)
         end

data/lib/tahweel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tahweel
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/tahweel/writer.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "writers/txt"
 require_relative "writers/docx"
 require_relative "writers/json"
+require_relative "writers/txt"
 
 module Tahweel
   # Factory class for writing extracted text to different formats.

data/lib/tahweel/writers/docx.rb

@@ -14,10 +14,11 @@ module Tahweel
       # Writes the extracted texts to a file.
       #
       # It applies several transformations to the text before writing:
-      # 1. Normalizes line endings to `\n`.
+      # 1. Normalizes all line endings (`\r\n`, `\r`) to `\n`.
       # 2. Collapses consecutive identical whitespace characters.
       # 3. Compacts the text by merging short lines if the page is too long (> 40 lines).
       # 4. Determines text alignment (RTL/LTR) based on content.
+      # 5. Converts `\n` to proper OOXML line breaks for cross-platform compatibility.
       #
       # @param texts [Array<String>] The extracted texts (one per page).
       # @param destination [String] The output file path.
@@ -26,10 +27,10 @@ module Tahweel
       def write(texts, destination, options = {}) # rubocop:disable Lint/UnusedMethodArgument
         Caracal::Document.save(destination) do |docx|
           texts.each_with_index do |text, index|
-            text = text.gsub(/(\r\n)+/, "\n").gsub(/(\s)\1+/, '\1').strip
+            text = text.gsub(/\r\n?/, "\n").gsub(/(\s)\1+/, '\1').strip
             text = compact_shortest_lines(text) while expected_lines_in_page(text) > 40
 
-            docx.p text, size: 20, align: alignment_for(text)
+            write_paragraph(docx, text)
 
             docx.page if index < texts.size - 1
           end
@@ -38,6 +39,28 @@ module Tahweel
 
       private
 
+      # Writes a paragraph with proper OOXML line breaks.
+      #
+      # Raw newline characters (\n, \r\n) are not valid line breaks in DOCX format.
+      # Microsoft Word on Windows requires proper <w:br/> elements for line breaks,
+      # while macOS Pages is more lenient. This method uses Caracal's `br` method
+      # to insert cross-platform compatible line breaks.
+      #
+      # @param docx [Caracal::Document] The document to write to.
+      # @param text [String] The text content with newlines.
+      # @return [void]
+      def write_paragraph(docx, text)
+        lines = text.split("\n")
+        alignment = alignment_for(text)
+
+        docx.p align: alignment do
+          lines.each_with_index do |line, line_index|
+            text line, size: 20
+            br if line_index < lines.size - 1
+          end
+        end
+      end
+
       # Determines the text alignment based on the ratio of Arabic to non-Arabic characters.
       #
       # @param text [String] The text to analyze.

data/lib/tahweel.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
 require_relative "tahweel/version"
+require_relative "tahweel/cli/options"
+require_relative "tahweel/cli/file_processor"
+require_relative "tahweel/cli/file_collector"
 require_relative "tahweel/authorizer"
+require_relative "tahweel/poppler_installer"
 require_relative "tahweel/pdf_splitter"
 require_relative "tahweel/ocr"
+require_relative "tahweel/processors/google_drive"
 require_relative "tahweel/converter"
 require_relative "tahweel/writer"
-require_relative "tahweel/cli/file_processor"
-require_relative "tahweel/cli/file_collector"
-require_relative "tahweel/cli/options"
+require_relative "tahweel/writers/txt"
+require_relative "tahweel/writers/docx"
+require_relative "tahweel/writers/json"
 
 module Tahweel # rubocop:disable Style/Documentation
   class Error < StandardError; end