pdfh 3.1.0 → 3.3.0

data/lib/pdfh/main.rb

@@ -4,13 +4,12 @@ module Pdfh
   # Main functionality. This class is intended to manage the pdf documents
   class Main
     class << self
+      # @param argv [Array<String>]
       # @return [void]
-      def start
-        arg_options = Pdfh::OptParser.parse_argv
+      def start(argv:)
+        arg_options = Pdfh::OptParser.new(argv: argv).parse_argv
         @options = Options.new(arg_options)
-
-        Pdfh.instance_variable_set(:@options, options)
-        Pdfh.instance_variable_set(:@console, Console.new(options.verbose?))
+        assign_global_utils(@options)
         Pdfh.print_options(arg_options)
 
         @settings = SettingsBuilder.build
@@ -22,6 +21,7 @@ module Pdfh
         Pdfh.create_settings_file
         exit(1)
       rescue StandardError => e
+        Pdfh.backtrace_print e if Pdfh.verbose?
         Pdfh.error_print(e.message)
       end
 
@@ -29,8 +29,15 @@ module Pdfh
 
       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]
+      # @return [DocumentType, nil]
       def match_doc_type(file_name)
         settings.document_types.each do |type|
           match = type.re_file.match(file_name)
@@ -63,31 +70,74 @@ module Pdfh
 
       # @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))
+
+            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
+
+      # @param directory [String]
+      # @param type [String, Symbol]
+      # @return [Array<String>]
+      def find_files(directory, type)
+        glob = File.join(directory, "*.#{type}")
+        Dir.glob(glob)
+      end
+
       def process_directory(work_directory)
         Pdfh.headline(work_directory)
-        processed_count = 0
-        ignored_files = []
-        files = Dir["#{work_directory}/*.pdf"]
+        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
-            processed_count += 1
             PdfFileHandler.new(pdf_file, type).process_document(settings.base_path)
+            processed_result.add_processed(pdf_file)
           else
-            ignored_files << base_name_no_ext(pdf_file)
+            processed_result.add_ignored(pdf_file)
           end
         end
-        puts "  (No files processed)".colorize(:light_black) if processed_count.zero?
-        return unless Pdfh.verbose?
-
-        puts "\n  No document type found for these PDF files:" if ignored_files.any?
-        ignored_files.each.with_index(1) { |file, index| Pdfh.ident_print index, file, color: :magenta }
+        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
+        end
+      end
+    end
+
+    # keeps track of the processed and ignored files
+    class RunResult
+      attr_reader :processed, :ignored
+
+      # @return [self]
+      def initialize
+        @processed = []
+        @ignored = []
+      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

@@ -12,14 +12,18 @@ module Pdfh
     def initialize(file, type, text)
       @file = file
       @type = type
-      Pdfh.debug "=== Document Type: #{type.name} =============================="
       @text = text
+    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_data
+      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
@@ -32,7 +36,6 @@ module Pdfh
       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 "Print CMD", print_cmd
       print_info_line "Processed?", "No (in Dry mode)" if Pdfh.dry?
     end
 
@@ -95,14 +98,6 @@ module Pdfh
       type.generate_path(rename_data)
     end
 
-    # @return [String]
-    def print_cmd
-      return "N/A" if type.print_cmd.nil? || type.print_cmd.empty?
-
-      relative_path = File.join(store_path, new_name)
-      "#{type.print_cmd} #{relative_path}"
-    end
-
     # @return [String (frozen)]
     def companion_files(join: false)
       return @companion unless join
@@ -125,16 +120,17 @@ module Pdfh
     # 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]
-    def match_data
+    # @param regex [RegularExpression]
+    def match_date(regex)
       Pdfh.debug "~~~~~~~~~~~~~~~~~~ Match Data RegEx"
-      Pdfh.debug "  Using regex: #{@type.re_date}"
-      Pdfh.debug "        named:   #{@type.re_date.named_captures}"
-      matched = @type.re_date.match(@text)
+      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 @type.re_date.named_captures.empty?
+      return matched.captures.map(&:downcase) if regex.named_captures.empty?
 
       extra = matched.captures.size > 2 ? matched[:d] : nil
       [matched[:m].downcase, matched[:y], extra]

data/lib/pdfh/models/document_sub_type.rb

@@ -2,5 +2,5 @@
 
 module Pdfh
   # Provides a way to divide document type by subtypes, for different name, and month adjustments
-  DocumentSubType = Struct.new(:name, :month_offset, keyword_init: true)
+  DocumentSubType = Struct.new(:name, :month_offset, :re_date, keyword_init: true)
 end

data/lib/pdfh/models/document_type.rb

@@ -2,15 +2,33 @@
 
 module Pdfh
   # Represents a type of document that can be processed by pdfh
-  DocumentType = Struct.new(:name, :re_file, :re_date, :pwd, :store_path, :name_template, :sub_types, :print_cmd,
-                            keyword_init: true) do
+  class DocumentType
+    include Concerns::PasswordDecodable
+
+    # @!attribute [r] name
+    #   @return [String] The name of the document type.
+    # @!attribute [r] re_file
+    #   @return [Regexp] The regular expression to match file names.
+    # @!attribute [r] re_date
+    #   @return [Regexp] The regular expression to extract dates and its information.
+    # @!attribute [r] pwd
+    #   @return [String, nil] The base64 password for the document type, if any.
+    # @!attribute [r] store_path
+    #   @return [String] The path where the document will be stored.
+    # @!attribute [r] name_template
+    #   @return [String] The template for generating document names.
+    # @!attribute [r] sub_types
+    #   @return [Array<DocumentSubType>, nil] The subtypes of the document, if any.
+    attr_reader :name, :re_file, :re_date, :pwd, :store_path, :name_template, :sub_types
+
+    # @param args [Hash]
     # @return [self]
     def initialize(args)
-      super
-      self.name_template ||= "{original}"
-      self.re_file = Regexp.new(re_file)
-      self.re_date = Regexp.new(re_date)
-      self.sub_types = extract_subtype(sub_types) if sub_types
+      args.each { |k, v| instance_variable_set(:"@#{k}", v) }
+      @name_template ||= "{original}"
+      @re_file = Regexp.new(re_file)
+      @re_date = Regexp.new(re_date)
+      @sub_types = extract_subtypes(sub_types) if sub_types&.any?
       @path_validator = RenameValidator.new(store_path)
       @name_validator = RenameValidator.new(name_template)
       return if @path_validator.valid? && @name_validator.valid?
@@ -18,6 +36,11 @@ module Pdfh
       raise_validators_error
     end
 
+    # @return [Hash{Symbol->any}]
+    def to_h
+      instance_variables.to_h { |var| [var.to_s.delete_prefix("@"), instance_variable_get(var)] }
+    end
+
     # removes special characters from string and replaces spaces with dashes
     # @example usage
     #   "Test This?%&".gid
@@ -27,19 +50,13 @@ module Pdfh
       name.downcase.gsub(/[^0-9A-Za-z\s]/, "").tr(" ", "-")
     end
 
+    # search the subtype name in the pdf document
     # @return [DocumentSubType]
     def sub_type(text)
       # Regexp.new(st.name).match?(name)
       sub_types&.find { |st| /#{st.name}/i.match?(text) }
     end
 
-    # @return [String]
-    def password
-      return Base64.decode64(pwd) if base64?
-
-      pwd
-    end
-
     # @param values [Hash{Symbol->String}
     # @return [String]
     def generate_new_name(values)
@@ -54,28 +71,29 @@ module Pdfh
 
     private
 
-    # @return [boolean]
-    def base64?
-      pwd.is_a?(String) && Base64.strict_encode64(Base64.decode64(pwd)) == pwd
-    end
+    attr_accessor :path_validator, :name_validator
 
-    # @param sub_types [Array]
-    # @return [DocumentSubType]
-    def extract_subtype(sub_types)
+    # @param sub_types [Array<Hash{Symbol->String}>]
+    # @return [Array<DocumentSubType>]
+    def extract_subtypes(sub_types)
       sub_types.map do |st|
-        name = st[:name]
-        offset = st[:month_offset].to_i
-        DocumentSubType.new(name: name, month_offset: offset)
+        data = {
+          name: st[:name],
+          month_offset: st[:month_offset].to_i,
+          re_date: st[:re_date] && Regexp.new(st[:re_date])
+        }.compact
+        DocumentSubType.new(data)
       end
     end
 
     # @raise [ArgumentError] when called
     # @return [void]
     def raise_validators_error
-      template = "has invalid %<1>s. Unknown tokens: %<2>s"
-      path_errors = format(template, :store_path, @path_validator.unknown_list) unless @path_validator.valid?
-      name_errors = format(template, :name_template, @name_validator.unknown_list) unless @name_validator.valid?
-      raise ArgumentError, "Document type #{name.inspect} #{path_errors} #{name_errors}"
+      template = "has invalid %<field>s[Unknown tokens=%<error>s]"
+      errors = []
+      errors << format(template, field: :store_path, error: path_validator.unknown_list) unless path_validator.valid?
+      errors << format(template, field: :name_template, error: name_validator.unknown_list) unless name_validator.valid?
+      raise ArgumentError, "Document type #{name.inspect} #{errors.join(", ")}"
     end
   end
 end

data/lib/pdfh/models/settings.rb

@@ -3,7 +3,13 @@
 module Pdfh
   # Handles the config yaml data mapping, and associates a file name with a doc type
   class Settings
-    attr_reader :lookup_dirs, :base_path
+    # @!attribute [r] lookup_dirs
+    #   @return [Array<String>] List of directories to look up for processing.
+    # @!attribute [r] base_path
+    #   @return [String] The base directory path for storing processed files.
+    # @!attribute [r] zip_types
+    #   @return [Array<ZipType>, nil] List of zip types to process, or nil if none.
+    attr_reader :lookup_dirs, :base_path, :zip_types
 
     # @param config_data [Hash]
     # @return [self]
@@ -15,7 +21,8 @@ module Pdfh
       lookup_dirs.each.with_index(1) { |dir, idx| Pdfh.debug "  #{idx}. #{dir}" }
       Pdfh.debug
 
-      load_doc_types(config_data[:document_types])
+      build_doc_types(config_data[:document_types])
+      build_zip_types(config_data[:zip_types]) if config_data.key?(:zip_types)
     end
 
     # @return [Array<DocumentType>]
@@ -28,8 +35,14 @@ module Pdfh
       @document_types[id]
     end
 
+    # @return [Boolean]
+    def zip_types?
+      !!zip_types&.any?
+    end
+
     private
 
+    # @param lookup_dirs_list [Array[String]]
     # @return [void]
     def process_lookup_dirs(lookup_dirs_list)
       @lookup_dirs = lookup_dirs_list.filter_map do |dir|
@@ -44,20 +57,31 @@ module Pdfh
     end
 
     # @return [void]
+    # @param dir [String]
     def process_destination_base(dir)
       @base_path = File.expand_path(dir)
       raise ArgumentError, "Destination base directory is not configured." if @base_path.nil?
       raise ArgumentError, "Destination base directory #{@base_path} does not exist." unless File.directory?(@base_path)
     end
 
-    # @return [Array<DocumentType>]
-    def load_doc_types(doc_types)
+    # @param doc_types [Array<Hash>]
+    # @return [void]
+    def build_doc_types(doc_types)
       @document_types = doc_types.each_with_object({}) do |data, result|
         doc_type = DocumentType.new(data)
         result.store(doc_type.gid, doc_type)
       rescue ArgumentError => e
         Pdfh.error_print e.message, exit_app: false
+        Pdfh.backtrace_print e if Pdfh.verbose?
       end
     end
+
+    # @param zip_types [Array<Hash>]
+    # @return [void]
+    def build_zip_types(zip_types)
+      exit(1) if Pdfh::Utils::DependencyValidator.missing?(:unzip)
+
+      @zip_types = zip_types.compact.map { ZipType.new(_1) }
+    end
   end
 end

data/lib/pdfh/models/zip_types.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pdfh
+  # Zip files which contains PDF files that need pre-processing
+  class ZipType
+    include Concerns::PasswordDecodable
+
+    attr_reader :name, :re_file, :pwd
+
+    # @param args [Hash]
+    # @return [self]
+    def initialize(args)
+      args.each { |k, v| instance_variable_set(:"@#{k}", v) }
+      @re_file = Regexp.new(re_file)
+    end
+  end
+end

data/lib/pdfh/utils/console.rb

@@ -41,6 +41,14 @@ module Pdfh
       exit 1 if exit_app
     end
 
+    # @param e [StandardError]
+    # @return [void]
+    def backtrace_print(e)
+      e.backtrace&.each do |line|
+        output "  ↳ #{line.sub("#{Dir.pwd}/", "")}".colorize(:light_black)
+      end
+    end
+
     # @param message [String]
     # @return [void]
     def warn_print(message)

data/lib/pdfh/utils/dependency_validator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Pdfh
+  module Utils
+    # Provides methods to validate external dependencies
+    module DependencyValidator
+      module_function
+
+      # Validates if the required command-line applications are installed
+      # @param apps [Array<String>] names of required command-line applications
+      # @return [Boolean] true if all applications are installed, false otherwise
+      def installed?(*apps)
+        missing = apps.filter_map do |app|
+          _stdout, _stderr, status = Open3.capture3("which #{app}")
+
+          app.to_s unless status.success?
+        end
+
+        if missing.any?
+          errors = missing.map(&:red)
+          puts "Required dependency #{errors.join(", ")} not found. Please install it before continuing."
+        end
+        missing.empty?
+      end
+
+      # @param apps [Array<String>]
+      # @return [Boolean] true if any application is missing, false if all are installed
+      def missing?(*apps)
+        !installed?(*apps)
+      end
+    end
+  end
+end

data/lib/pdfh/utils/opt_parser.rb

@@ -5,58 +5,73 @@ require "optparse"
 module Pdfh
   # Handles Argument options
   class OptParser
-    OPT_PARSER = OptionParser.new do |opts|
-      opts.default_argv
-      # Process ARGV
-      opts.banner = "Usage: #{opts.program_name} [options] [file1 ...]"
-      opts.separator ""
-      opts.separator "Specific options:"
-
-      opts.on("-tID", "--type=ID", "Document type id (requires a trailing file list)")
-      opts.on_tail("-T", "--list-types", "List document types in configuration") { list_types || exit }
-      opts.on_tail("-V", "--version", "Show version") { version || exit }
-      opts.on_tail("-h", "--help", "help (this dialog)") { help || exit }
-
-      opts.on("-v", "--verbose", "Show more output. Useful for debug")
-      opts.on("-d", "--dry", "Dry run, does not write new pdf")
+    # @param argv [Array<String>] command line arguments (ie. ARGV)
+    # @param console [Pdfh::Console, nil]
+    # @return [self]
+    def initialize(argv:, console: nil)
+      @argv = argv
+      @console = console || Console.new(false)
+      @options = {
+        verbose: false,
+        dry: false,
+        type: nil,
+        files: []
+      }
     end
 
-    class << self
-      # @return [Hash]
-      def parse_argv
-        Pdfh.instance_variable_set(:@console, Console.new(false))
-
-        options = { dry: false, verbose: false }
-        OPT_PARSER.parse!(into: options)
-        options[:files] = ARGV if ARGV.any?
-        options.transform_keys { |key| key.to_s.tr("-", "_").to_sym }
-      rescue OptionParser::InvalidOption => e
-        Pdfh.error_print(e.message, exit_app: false)
-        puts OPT_PARSER.help
-        exit 1
-      end
+    # @return [Hash] Parsed options including flags and file arguments
+    def parse_argv
+      option_parser = build_option_parser
+      non_option_args = option_parser.parse!(@argv)
+      @options[:files] = non_option_args
+      @options.transform_keys { |key| key.to_s.tr("-", "_").to_sym }
+    rescue OptionParser::InvalidOption => e
+      @console.error_print(e.message, exit_app: false)
+      puts option_parser.help
+      exit 1
+    end
 
-      # @return [nil]
-      def version
-        puts "#{OPT_PARSER.program_name} v#{Pdfh::VERSION}"
-      end
+    private
 
-      # @return [nil]
-      def help
-        puts OPT_PARSER
+    # @return [OptionParser] Configured OptionParser instance
+    def build_option_parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: #{opts.program_name} [options] [file1.pdf, ...]"
+        opts.separator ""
+        opts.separator "Specific options:"
+
+        opts.on("-tID", "--type=ID", "Document type id (requires a trailing file list)") { @options[:type] = _1 }
+        opts.on("-v", "--verbose", "Show more output. Useful for debug") { @options[:verbose] = true }
+        opts.on("-d", "--dry", "Dry run, does not write new pdf") { @options[:dry] = true }
+        opts.on_tail("-T", "--list-types", "List document types in configuration") { list_types && exit }
+        opts.on_tail("-V", "--version", "Show version") { version || exit }
+        opts.on_tail("-h", "--help", "help (this dialog)") { help || exit }
       end
+    end
+
+    # @return [nil]
+    def version
+      @console.info "#{build_option_parser.program_name} v#{Pdfh::VERSION}"
+    end
+
+    # @return [nil]
+    def help
+      @console.info build_option_parser
+    end
+
+    # Lists the available document types
+    # @return [nil]
+    def list_types
+      Pdfh.instance_variable_set(:@options, Options.new(@options))
+      Pdfh.instance_variable_set(:@console, @console)
 
-      # @return [nil]
-      def list_types
-        settings = SettingsBuilder.build
-        ident = 2
-        max_width = settings.document_types.map { |t| t.gid.size }.max
-        puts "#{" " * ident}#{"ID".ljust(max_width)}  Type Name"
-        puts "#{" " * ident}#{"—" * max_width}  #{"—" * 23}"
-        settings.document_types.each do |type|
-          puts "#{" " * ident}#{type.gid.ljust(max_width).yellow}  #{type.name}"
-        end
-        nil
+      settings = SettingsBuilder.build
+      spacing = " " * 2
+      max_width = settings.document_types.map { |t| t.gid.size }.max
+      @console.info "#{spacing}#{"ID".ljust(max_width)}  Type Name"
+      @console.info "#{spacing}#{"—" * max_width}  #{"—" * 23}"
+      settings.document_types.each do |type|
+        @console.info "#{spacing}#{type.gid.ljust(max_width).yellow}  #{type.name}"
       end
     end
   end

data/lib/pdfh/utils/pdf_file_handler.rb

@@ -25,6 +25,7 @@ module Pdfh
       raise IOError, "File #{file} not found" unless File.exist?(file)
 
       @document = Document.new(file, type, extract_text)
+      document.process
       document.print_info
       write_pdf(base_path)
 
@@ -86,7 +87,7 @@ module Pdfh
     end
 
     # Gets the text from the pdf in order to execute
-    # the regular expresion matches
+    # the regular expression matches
     # @return [String]
     def extract_text
       temp = Tempfile.new("pdfh")

data/lib/pdfh/utils/settings_builder.rb

@@ -3,13 +3,17 @@
 module Pdfh
   # Loads or creates a default settings yaml file
   class SettingsBuilder
-    CONFIG_FILE_LOCATIONS = [Dir.pwd, File.expand_path("~")].freeze
+    CONFIG_FILE_LOCATIONS = [Dir.pwd, ENV.fetch("XDG_CONFIG_HOME", "~/.config"), "~"].freeze
     SUPPORTED_EXTENSIONS = %w[yml yaml].freeze
+    ENV_VAR = "PDFH_CONFIG_FILE"
 
     class << self
       # @return [Pdfh::Settings]
       def build
-        config_file = search_config_file
+        env_config_file = ENV.fetch(ENV_VAR, nil)
+        raise "File path in #{ENV_VAR} not found" if env_config_file && !File.exist?(env_config_file)
+
+        config_file = env_config_file || search_config_file
         file_hash = YAML.load_file(config_file, symbolize_names: true)
         Pdfh.debug "Loaded configuration file: #{config_file}"
 
@@ -42,7 +46,8 @@ module Pdfh
       # Gets the first settings file found, or creates a new one
       # @return [String]
       def search_config_file
-        CONFIG_FILE_LOCATIONS.each do |dir|
+        CONFIG_FILE_LOCATIONS.each do |dir_string|
+          dir = File.expand_path(dir_string)
           SUPPORTED_EXTENSIONS.each do |ext|
             path = File.join(dir, "#{config_file_name}.#{ext}")
             return path if File.exist?(path)

data/lib/pdfh/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pdfh
-  VERSION = "3.1.0"
+  VERSION = "3.3.0"
 end