pdfh 3.3.1 → 4.0.1

data/README.md

@@ -5,7 +5,7 @@
 [![Conventional Commits][cc-img]][cc-url]
 [![Current version][gem-img]][gem-url]
 
-Examine all PDF files in lookup directories, remove passwords (if present), rename them, and copy them to a new directory using regular expressions.
+Examine all PDF files in lookup directories, identify them using regular expressions, rename them, and copy them to organized directories.
 
 ## Installation
 
@@ -15,34 +15,52 @@ gem install pdfh
 
 ### Dependencies
 
-You need to install pdf handling dependencies in order to use this gem.
+You need to install `pdftotext` to extract text from PDF files.
 
 #### macOS
 
 ```bash
-brew install qpdf xpdf # < for pdftotext
+brew install xpdf
 ```
 
 #### Fedora
 
 ```bash
-sudo dnf install -y qpdf poppler-utils
+sudo dnf install -y poppler-utils
 ```
 
 #### Arch
 
 ```bash
-sudo pacman -S qpdf poppler
+sudo pacman -S poppler
 ```
 
 ## Usage
 
 After installing this gem, create your configuration file in one of the following directories:
+
 - `~/.config/pdfh.yml`
 - `~/pdfh.yml`
 - or configure the `PDFH_CONFIG_FILE` environment variable
 
+Then run:
+
+```bash
+pdfh
+```
+
+The tool will:
+
+1. Scan all PDFs in the configured `lookup_dirs`
+2. Extract text from each PDF using `pdftotext`
+3. Match the extracted text from each PDF against your configured `document_types` (via `re_id`)
+4. Copy matched documents to organized directories within `destination_base_path`
+5. Rename files according to your `name_template`
+
+### Configuration
+
 Example configuration:
+
 ```yaml
 ---
 lookup_dirs:                   # Directories where all PDFs will be analyzed
@@ -50,45 +68,42 @@ lookup_dirs:                   # Directories where all PDFs will be analyzed
 destination_base_path: ~/PDFs  # Directory where all matching documents will be copied (MUST exist)
 document_types:
   - name: My Bank                         # Description (type)
-    re_file: '.*MyBankReg\.pdf'           # Regular expression to match its filename
-    re_date: '\d{1,2} de (\w+) de (\d+)'  # Date regular expression
-    pwd: base64_encoded                   # [OPTIONAL] Password if the document is protected
+    re_id: 'Account ID: 12334-\w{3}'      # [OPTIONAL (uses name as fallback)] RegEx to match from PDF content as document identifier
+    re_date: '\d{1,2} de (\w+) de (\d+)'  # Date RegEx (to extract from PDF content)
     store_path: "{year}/bank_docs"        # Relative path to copy this document
-    name_template: '{period} {subtype}'   # Template for new filename when copied
-    sub_types:                            # [OPTIONAL] In case your need an extra category
-      - name: AccountX                       # Regular expression to match this subtype
-        re_date: '\d{1,2} de (\w+)'          # [OPTIONAL] Date regular expression
-        month_offset: -1                     # [OPTIONAL] Integer (signed) value to adjust month
-zip_types:                     # [OPTIONAL] Zip files to be processed BEFORE the PDFs
-  - name: My Bank 2                          # Description
-    re_file: 'Document_MR5664_\d+_\d+.zip'   # Regular expression to match its filename
-    pwd: base64_encoded                      # [OPTIONAL] Password if the document is protected
+    name_template: '{period} {name}'      # [OPTIONAL] Template for new filename when copied
 ```
 
-> [!CAUTION]
-> `pwd` is not encrypted, so be careful with this option. It is stored as a base64 string as a very thin layer of obfuscation.
-> You can use `echo -n 'password' | base64` to encode your password.
+### Placeholders
+
+**Store Path** and **Name Template** support the following placeholders:
 
-**Store Path** and **Name Template** supported placeholders:
+| Placeholder | Description | Example |
+| --- | --- | --- |
+| `{original}` | Original filename | `MyBankDocument2.pdf` |
+| `{period}` | Year-Month | `2022-07` |
+| `{year}` | Year | `2022` |
+| `{month}` | Month | `07` |
+| `{day}` | Day (if captured) | `01` |
+| `{quarter}` | Quarter (Q1-Q4) | `Q3` |
+| `{bimester}` | Bimester (B1-B6) | `B4` |
+| `{name}` | Document type **name** | `My Bank` |
 
-Placeholder | Description               | Example
---- |---------------------------| ---
-`{original}` | Original filename         | MyBankDocument2.pdf
-`{period}`   | Year-Month                | 2022-01
-`{year}`     | Year                      | 2022
-`{month}`    | Month                     | 01
-`{type}`     | Document type **name**    | My Bank
-`{subtype}`  | Sub type **name**         | AccountX
-`{extra}`    | day if captured/matched   | 01
+The `period`, `year`, `month`, `day`, `quarter` and `bimester` placeholders are calculated from the date captured by the `re_date` regular expression.
 
-`period`, `year`, `month` and `{extra}` are calculated from the date captured by the regular expression.
+### Date Extraction Examples
 
-### Examples
+The `re_date` regex extracts date information from the PDF content:
 
-Date text | RegEx | Captured
---- | --- | ---
-`01/02/2025` | `(?<d>\d{2}\/(?<m>\d{2})\/(?<y>\d{4})` | d: `01` m: `02` y: `2025`
-`072025 - ` | `(?<m>\d{2})(?<y>\d{4}) -` | m: `07` y: `2025`
+| Date text | RegEx | Captured |
+| --- | --- | --- |
+| `01/02/2025` | `(?<d>\d{2})\/(?<m>\d{2})\/(?<y>\d{4})` | d: `01` m: `02` y: `2025` |
+| `072025 -` | `(?<m>\d{2})(?<y>\d{4}) -` | m: `07` y: `2025` |
+| `31 de julio de 2025` | `\d{1,2} de (\w+) de (\d+)` | month: `julio` year: `2025` |
+
+Named captures supported: `y` for year, `m` for month, `d` for day.
+
+If named captures are not used, the regex groups will be matched in order: `month`, `year`.
 
 ## Development
 
@@ -132,10 +147,30 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 Everyone interacting in the Pdfh project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/iax7/pdfh/blob/master/CODE_OF_CONDUCT.md).
 
+## Command Options
+
+Run with verbose output:
+
+```bash
+pdfh -v
+```
+
+Run in dry-run mode (no files will be moved):
+
+```bash
+pdfh --dry
+```
+
+Show version:
+
+```bash
+pdfh --version
+```
+
 <!-- Links -->
 [rubocop-img]: https://github.com/iax7/pdfh/actions/workflows/rubocop-analysis.yml/badge.svg
 [rubocop-url]: https://github.com/iax7/pdfh/actions/workflows/rubocop-analysis.yml
-[ruby-img]: https://img.shields.io/badge/ruby-3.4-blue?style=flat&logo=ruby&logoColor=CC342D&labelColor=white
+[ruby-img]: https://img.shields.io/badge/ruby-4.0-blue?style=flat&logo=ruby&logoColor=CC342D&labelColor=white
 [ruby-url]: https://www.ruby-lang.org/en/
 [cc-img]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=00&labelColor=fff
 [cc-url]: https://conventionalcommits.org

data/Rakefile

@@ -3,7 +3,6 @@
 require "colorize"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "versionomy"
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -16,13 +15,32 @@ task :bump, :type do |_t, args|
   version_file = File.join(__dir__, "lib", "pdfh", "version.rb")
   content = File.read(version_file)
 
-  version_pattern = /(?<major>\d+)\.(?<minor>\d+)\.(?<tiny>\d+)/
-  current_version = content.match(version_pattern)
-  next_version    = Versionomy.parse(current_version.to_s).bump(args.type).to_s
+  version_pattern = /VERSION = "(?<major>\d+)\.(?<minor>\d+)\.(?<tiny>\d+)"/
+  match = content.match(version_pattern)
 
-  File.write(version_file, content.gsub(version_pattern, "\\1#{next_version}\\3"))
+  major = match[:major].to_i
+  minor = match[:minor].to_i
+  tiny = match[:tiny].to_i
 
-  puts "Successfully bumped from #{current_version.to_s.red} to #{next_version.green}"
+  case args.type.to_sym
+  when :major
+    major += 1
+    minor = 0
+    tiny = 0
+  when :minor
+    minor += 1
+    tiny = 0
+  when :tiny
+    tiny += 1
+  end
+
+  current_version = "#{match[:major]}.#{match[:minor]}.#{match[:tiny]}"
+  next_version = "#{major}.#{minor}.#{tiny}"
+
+  new_content = content.gsub(version_pattern, "VERSION = \"#{next_version}\"")
+  File.write(version_file, new_content)
+
+  puts "Successfully bumped from #{current_version.red} to #{next_version.green}"
   puts "\n> Building v#{next_version.green}..."
   puts `rake build`
 end

data/bin/console

@@ -5,14 +5,7 @@ require "bundler/setup"
 require "pdfh"
 
 # You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+# with your gem easier.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
-
-p Pdfh::OptParser.parse_argv
-
-Pry.start
-
-# require "irb"
-# IRB.start(__FILE__)
+require "irb"
+IRB.start(__FILE__)

data/bin/run

@@ -4,7 +4,6 @@
 require "bundler/setup"
 require "debug"
 require "pdfh"
-require "pry"
 
 exit(1) if Pdfh::Utils::DependencyValidator.missing?(*Pdfh::REQUIRED_CMDS)
 

data/exe/pdfh

@@ -8,5 +8,5 @@ exit(1) if Pdfh::Utils::DependencyValidator.missing?(*Pdfh::REQUIRED_CMDS)
 begin
   Pdfh::Main.start(argv: ARGV)
 rescue StandardError => e
-  Pdfh.error_print e.message
+  Pdfh.logger.error_print e.message
 end

data/justfile

@@ -0,0 +1,65 @@
+# Run commands through bundle if present
+
+set shell := ["bash", "-c"]
+
+# List all available tasks
+default:
+    @just --list
+
+# --- Installation and setup ---
+
+# Install gems and system dependencies via mise
+[group('setup')]
+setup:
+    mise install
+    bundle install
+
+# Update gems
+[group('setup')]
+update:
+    bundle update --bundler
+    bundle update --all
+
+# --- Testing and quality ---
+
+# Run all checks (linting and tests)
+[group('test')]
+check: lint test
+
+# Run all tests with RSpec
+[group('test')]
+test:
+    bundle exec rspec
+
+# Run a specific test (e.g., just test-file spec/models/user_spec.rb:42)
+[group('test')]
+test-file path:
+    bundle exec rspec {{ path }}
+
+# Run the linter (RuboCop) and auto-fix simple issues
+[group('test')]
+lint:
+    bundle exec rubocop -a
+
+# Open coverage HTML report
+[group('test')]
+coverage:
+    @[[ -f coverage/index.html ]] && open coverage/index.html || echo "Coverage report not found"
+
+# --- Version management and release ---
+
+# Bump version (major|minor|tiny)
+[group('release')]
+bump type='tiny':
+    bundle exec rake "bump[{{ type }}]"
+    bundle install
+
+# Build and install the gem locally
+[group('release')]
+install:
+    bundle exec rake install
+
+# Create a git tag, build and push gem to RubyGems
+[group('release')]
+release:
+    bundle exec rake release

data/lib/pdfh/main.rb

@@ -7,137 +7,42 @@ module Pdfh
       # @param argv [Array<String>]
       # @return [void]
       def start(argv:)
-        arg_options = Pdfh::OptParser.new(argv: argv).parse_argv
-        @options = Options.new(arg_options)
-        assign_global_utils(@options)
-        Pdfh.print_options(arg_options)
+        arg_options = Services::OptParser.new(argv: argv).parse_argv
+        options = RunOptions.new(**arg_options)
 
-        @settings = SettingsBuilder.build
-        Pdfh.debug "Destination path: #{settings.base_path.colorize(:light_blue)}"
+        # Initialize the global logger
+        Pdfh.logger = Console.new(options.verbose?)
+        Pdfh.logger.print_options(arg_options)
 
-        options.file_mode? ? process_provided_files : process_lookup_dirs
-      rescue SettingsIOError => e
-        Pdfh.error_print(e.message, exit_app: false)
-        Pdfh.create_settings_file
-        exit(1)
-      rescue StandardError => e
-        Pdfh.backtrace_print e if Pdfh.verbose?
-        Pdfh.error_print(e.message)
-      end
-
-      private
-
-      attr_reader :options, :settings
-
-      # @param options [Options]
-      # @return [void]
-      def assign_global_utils(options)
-        Pdfh.instance_variable_set(:@options, options)
-        Pdfh.instance_variable_set(:@console, Console.new(options.verbose?))
-      end
-
-      # @param [String] file_name
-      # @return [DocumentType, nil]
-      def match_doc_type(file_name)
-        settings.document_types.each do |type|
-          match = type.re_file.match(file_name)
-          return type if match
-        end
-        nil
-      end
-
-      # @return [void]
-      def process_provided_files
-        type_id = options.type
-        raise ArgumentError, "No files provided to process #{type_id.inspect} type." unless options.files?
-
-        type = settings.document_type(type_id)
-        Pdfh.error_print "Type #{type_id.inspect} was not found." if type.nil?
-        options.files.each do |file|
-          next Pdfh.warn_print "File #{file.inspect} does not exist." unless File.exist?(file)
-          next Pdfh.warn_print "File #{file.inspect} is not a pdf." unless File.extname(file) == ".pdf"
-
-          PdfFileHandler.new(file, type).process_document(settings.base_path)
-        end
-      end
-
-      # @return [void]
-      def process_lookup_dirs
-        settings.lookup_dirs.each do |work_directory|
-          process_directory(work_directory)
-        end
-      end
+        settings = Services::SettingsBuilder.call
+        Pdfh.logger.debug "Destination path: #{settings.base_path.colorize(:light_blue)}"
 
-      # @param [String] work_directory
-      # @return [void]
-      def process_zip_files(work_directory)
-        @settings.zip_types&.each do |zip_type|
-          find_files(work_directory, :zip).each do |file|
-            next unless zip_type.re_file.match?(File.basename(file))
+        files = Services::DirectoryScanner.new(settings.lookup_dirs).scan
+        matcher = Services::DocumentMatcher.new(settings.document_types)
 
-            Pdfh.info " > Processing zip file: #{file.green}"
-            password_opt = "-P #{zip_type.password}" if zip_type.password?
-            `unzip -o #{password_opt} #{file} -d #{work_directory}`
-          end
-        end
-      end
+        files.each do |file_path|
+          Pdfh.logger.info "Working on: #{file_path.colorize(:green)}" if Pdfh.logger.verbose?
+          text = Services::PdfTextExtractor.call(file_path)
 
-      # @param directory [String]
-      # @param type [String, Symbol]
-      # @return [Array<String>]
-      def find_files(directory, type)
-        glob = File.join(directory, "*.#{type}")
-        Dir.glob(glob)
-      end
+          documents = matcher.match(file_path, text)
+          next Pdfh.logger.debug "No document type match found for #{file_path.colorize(:yellow)}" if documents.empty?
 
-      def process_directory(work_directory)
-        Pdfh.headline(work_directory)
-        process_zip_files(work_directory) if @settings.zip_types?
-        processed_result = RunResult.new
-        files = find_files(work_directory, :pdf)
-        files.each do |pdf_file|
-          type = match_doc_type(pdf_file)
-          if type
-            PdfFileHandler.new(pdf_file, type).process_document(settings.base_path)
-            processed_result.add_processed(pdf_file)
-          else
-            processed_result.add_ignored(pdf_file)
+          unless documents.one?
+            matches = documents.map { _1.type.name.inspect }.join(", ")
+            next Pdfh.logger.warn_print "Skipping #{file_path.inspect} as multiple matches found: #{matches}."
           end
-        end
-        print_processing_results(processed_result)
-      end
-
-      # @return [String]
-      def base_name_no_ext(file)
-        File.basename(file, File.extname(file))
-      end
-
-      def print_processing_results(result)
-        Pdfh.info "  (No files processed)".colorize(:light_black) if result.processed.empty?
-        return unless Pdfh.verbose?
 
-        Pdfh.info "\n  No document type found for these PDF files:" if result.ignored.any?
-        result.ignored.each.with_index(1) do |file, index|
-          Pdfh.ident_print index, base_name_no_ext(file), color: :magenta
+          Services::DocumentManager.new(documents.first, base_path: settings.base_path, dry_run: options.dry?).call
         end
-      end
-    end
-
-    # keeps track of the processed and ignored files
-    class RunResult
-      attr_reader :processed, :ignored
 
-      # @return [self]
-      def initialize
-        @processed = []
-        @ignored = []
+        nil
+      rescue SettingsIOError => e
+        Pdfh.logger.error_print(e.message, exit_app: false)
+        exit(1)
+      rescue StandardError => e
+        Pdfh.logger.backtrace_print(e) if Pdfh.logger.verbose?
+        Pdfh.logger.error_print(e.message)
       end
-
-      # @return [void]
-      def add_ignored(file) = @ignored << file
-
-      # @return [void]
-      def add_processed(file) = @processed << file
     end
   end
 end

data/lib/pdfh/models/document.rb

@@ -1,152 +1,67 @@
 # frozen_string_literal: true
 
 module Pdfh
-  # Handles the PDF detected by the rules
+  # Lightweight struct that connects a PDF file with its matched document type and
+  # extracted text. All file metadata, date interpretation, and rename resolution
+  # are accessible through dedicated value objects (FileInfo, DateInfo).
   class Document
-    attr_reader :text, :type, :file, :extra, :period
-
-    # @param file [String]
-    # @param type [DocumentType]
-    # @param text [String]
-    # @return [self]
-    def initialize(file, type, text)
-      @file = file
+    # @!attribute [r] file_info
+    #   @return [FileInfo] File metadata wrapper
+    # @!attribute [r] type
+    #   @return [DocumentType] Matched document type
+    # @!attribute [r] text
+    #   @return [String] Extracted text from the PDF
+    # @!attribute [r] date_info
+    #   @return [DateInfo] Parsed date value object
+    attr_reader :file_info, :type, :text, :date_info
+
+    # @param file [String] Path to the PDF file
+    # @param type [DocumentType] Type of the document
+    # @param text [String] Extracted text from the PDF
+    # @param date_captures [Hash{String => String}] Captured date components from regex
+    # @return [self] A new Document instance
+    def initialize(file, type, text, date_captures)
       @type = type
       @text = text
+      @file_info = FileInfo.new(file)
+      @date_info = DateInfo.new(date_captures)
     end
 
-    # @return [void]
-    def process
-      Pdfh.debug "=== Document Type: #{type.name} =============================="
-      Pdfh.debug "~~~~~~~~~~~~~~~~~~ Finding a subtype"
-      @sub_type = type.sub_type(@text)
-      Pdfh.debug "  SubType: #{@sub_type}"
-      @companion = search_companion_files
-
-      month, year, @extra = match_date(@sub_type&.re_date || @type.re_date)
-      @period = DocumentPeriod.new(day: extra, month: month, month_offset: @sub_type&.month_offset, year: year)
-      Pdfh.debug "  Period: #{@period.inspect}"
-    end
-
-    # @return [void]
-    def print_info
-      print_info_line "Type", type.name
-      print_info_line "Sub-Type", sub_type
-      print_info_line "Period", period
-      print_info_line "New Name", new_name
-      print_info_line "Store Path", store_path
-      print_info_line "Extra files", companion_files(join: true)
-      print_info_line "Processed?", "No (in Dry mode)" if Pdfh.dry?
-    end
-
-    # @return [void]
-    def print_info_line(property, info)
-      Pdfh.ident_print property, info.to_s, color: :light_blue, width: 12
-    end
-
-    # @return [String]
-    def file_name_only
-      File.basename(@file, file_extension)
-    end
-
-    # @return [String]
-    def file_extension
-      File.extname(@file)
-    end
-
-    # @return [String]
-    def file_name
-      File.basename(@file)
-    end
-
-    # @return [String]
-    def backup_name
-      "#{file_name}.bkp"
-    end
-
-    # @return [String]
+    # @return [String] Document type name or "N/A" if type is nil
     def type_name
-      type&.name&.titleize || "N/A"
-    end
-
-    # @return [String]
-    def sub_type
-      @sub_type&.name&.titleize || "N/A"
+      type&.name || "N/A"
     end
 
-    # @return [Hash{Symbol->String}]
-    def rename_data
-      {
-        original: file_name_only,
-        period: period.to_s,
-        year: period.year.to_s,
-        month: period.month.to_s,
-        type: type_name,
-        subtype: sub_type,
-        extra: extra || ""
-      }.freeze
+    # @return [String] File name
+    def to_s
+      file_info.name
     end
 
-    # @return [String]
+    # @return [String] New file name with extension (e.g., "2024-01 Cuenta.pdf")
     def new_name
-      new_name = type.generate_new_name(rename_data)
-      "#{new_name}#{file_extension}"
+      "#{@type.name_validator.gsub(rename_data)}#{@file_info.extension}"
     end
 
-    # @return [String]
+    # @return [String] Storage path for the document (e.g., "2024/Edo Cuenta")
     def store_path
-      type.generate_path(rename_data)
-    end
-
-    # @return [String (frozen)]
-    def companion_files(join: false)
-      return @companion unless join
-
-      @companion.empty? ? "N/A" : @companion.join(", ")
-    end
-
-    # @return [String]
-    def home_dir
-      File.dirname(@file)
-    end
-
-    # @return [String]
-    def to_s
-      @file
+      @type.path_validator.gsub(rename_data)
     end
 
     private
 
-    # named matches can appear in any order with names 'd', 'm' and 'y'
-    # unnamed matches needs to be in order month, year
-    # @return [Array] - format [month, year, day]
-    # @param regex [RegularExpression]
-    def match_date(regex)
-      Pdfh.debug "~~~~~~~~~~~~~~~~~~ Match Data RegEx"
-      Pdfh.debug "  Using regex: #{regex}"
-      Pdfh.debug "        named:   #{regex.named_captures}"
-      matched = regex.match(@text)
-      raise ReDateError unless matched
-
-      Pdfh.debug "     captured: #{matched.captures}"
-
-      return matched.captures.map(&:downcase) if regex.named_captures.empty?
-
-      extra = matched.captures.size > 2 ? matched[:d] : nil
-      [matched[:m].downcase, matched[:y], extra]
-    end
-
-    # @return [Array]
-    def search_companion_files
-      Pdfh.debug "~~~~~~~~~~~~~~~~~~ Searching Companion files"
-      Pdfh.debug "  Searching on: #{home_dir.inspect}"
-      Dir.chdir(home_dir) do
-        files_matching = Dir["#{file_name_only}.*"]
-        companion = files_matching.reject { |file| file.include? ".pdf" }
-        Pdfh.debug "    Found: #{companion.inspect}"
-
-        companion
-      end
+    # Used to replace variables in the rename pattern i.e {original}, {period}, etc.
+    # @return [Hash{Symbol => String}] Hash containing rename variables
+    def rename_data
+      @rename_data ||= {
+        original: @file_info.stem,
+        period: @date_info.period,
+        year: @date_info.year.to_s,
+        month: @date_info.month.to_s,
+        quarter: "Q#{@date_info.quarter}",
+        bimester: "B#{@date_info.bimester}",
+        name: @type.name,
+        day: @date_info.day || ""
+      }.freeze
     end
   end
 end