LittleWeasel 3.0.4 → 4.0.0

data/lib/LittleWeasel/modules/locale.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'language'
+require_relative 'region'
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to handle conversion of parts of a locale to
+    # their string counter parts.
+    module Locale
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.include(Language)
+        base.include(Region)
+      end
+
+      # class method inclusions for convenience.
+      module ClassMethods
+        def locale(language:, region: nil)
+          raise ArgumentError, 'Argument language does not respond to :downcase' unless language.respond_to? :downcase
+
+          if region.present? && !region.respond_to?(:upcase)
+            raise ArgumentError,
+              'Argument region does not respond to :upcase'
+          end
+
+          language = normalize_language language
+          return language.to_s unless region.present?
+
+          region = normalize_region region
+          "#{language}-#{region}"
+        end
+      end
+
+      def locale
+        self.class.locale language: language, region: region
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/order_validatable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a value that can be used
+    # in sorting.
+    module OrderValidatable
+      def self.validate(order:)
+        raise ArgumentError, "Argument order is not an Integer: #{order.class}" unless order.is_a? Integer
+        raise ArgumentError, "Argument order '#{order}' is not a a number from 0-n" if order.negative?
+      end
+
+      def validate_order(order:)
+        OrderValidatable.validate order: order
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/orderable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides attribtues and methods to manage objects that can be
+    # ordered or sorted.
+    module Orderable
+      include OrderValidatable
+
+      attr_reader :order
+
+      private
+
+      attr_writer :order
+    end
+  end
+end

data/lib/LittleWeasel/modules/region.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # Provides methods for normalizing a region for a locale.
+    module Region
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # class method inclusions for convenience.
+      module ClassMethods
+        def normalize_region(region)
+          region&.upcase
+        end
+      end
+
+      def normalize_region
+        self.class.normalize_region region
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/region_validatable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a region.
+    module RegionValidatable
+      def self.validate(region:)
+        raise ArgumentError, "Argument region '#{region}' is not a Symbol." unless region.blank? || region.is_a?(Symbol)
+      end
+
+      def validate_region(region:)
+        RegionValidatable.validate region: region
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/tag_validatable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a tag.
+    module TagValidatable
+      def self.validate(tag:)
+        raise ArgumentError, "Argument tag '#{tag}' is not a Symbol." unless tag.blank? || tag.is_a?(Symbol)
+      end
+
+      def validate_tag(tag:)
+        TagValidatable.validate tag: tag
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/taggable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'tag_validatable'
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to manage objects that can be tagged.
+    # A tag is a value that can be included as part of a DictionaryKey
+    # object to make it unique across locales.
+    #
+    # @examples
+    #
+    #   en-US-<tag>
+    #
+    #   Where <tag> = a String to make this locale unique across locales
+    #   of the same language and region.
+    module Taggable
+      include TagValidatable
+
+      attr_reader :tag
+
+      def tagged?
+        tag.present?
+      end
+
+      private
+
+      attr_writer :tag
+    end
+  end
+end

data/lib/LittleWeasel/modules/word_results_validatable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a word results
+    module WordResultsValidatable
+      def validate_original_word
+        raise ArgumentError, "Argument original_word is not a String: #{original_word.class}" \
+          unless original_word.is_a? String
+      end
+
+      def validate_filters_matched
+        raise ArgumentError, "Argument filters_matched is not an Array: #{filters_matched.class}" \
+          unless filters_matched.is_a? Array
+      end
+
+      def validate_word_cached
+        raise ArgumentError, "Argument word_cached is not true or false: #{word_cached.class}" \
+          unless [true, false].include? word_cached
+      end
+
+      def vaidate_word_valid
+        raise ArgumentError, "Argument word_valid is not true or false: #{word_cached.class}" \
+          unless [true, false].include? word_valid
+      end
+    end
+  end
+end

data/lib/LittleWeasel/preprocessors/en_us/capitalize_preprocessor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../word_preprocessor'
+
+module LittleWeasel
+  module Preprocessors
+    module EnUs
+      # This preprocessor capitializes a word.
+      class CapitalizePreprocessor < WordPreprocessor
+        def initialize(order: 0)
+          super
+        end
+
+        class << self
+          def preprocess(word)
+            [true, word.capitalize]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/preprocessors/preprocessed_word.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Preprocessors
+    # This class represents a word that has passed through
+    # Preprocessor::WordPreprocessor processing. Word preprocessors
+    # are used to preprocess a word before it is passed to any
+    # Filters::WordFilters, and before it is compared against the
+    # dictionary for validity.
+    class PreprocessedWord
+      attr_accessor :original_word, :preprocessed, :preprocessed_word, :preprocessor, :preprocessor_order
+
+      def initialize(original_word:, preprocessed:, preprocessed_word:, preprocessor:, preprocessor_order:)
+        self.original_word = original_word
+        self.preprocessed_word = preprocessed_word
+        self.preprocessed = preprocessed
+        self.preprocessor = preprocessor
+        self.preprocessor_order = preprocessor_order
+      end
+
+      # Returns true if the word was preprocessed; false, if the word
+      # was not preprocessed by this preprocessor.
+      def preprocessed?
+        preprocessed
+      end
+    end
+  end
+end

data/lib/LittleWeasel/preprocessors/preprocessed_word_validatable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Preprocessors
+    # This module provides functionality that validates preprocessed word types.
+    # rubocop: disable Layout/LineLength
+    module PreprocessedWordValidatable
+      module_function
+
+      def validate_prepreprocessed_word(preprocessed_word:)
+        validate_original_word preprocessed_word: preprocessed_word
+        validate_preprocessed_word preprocessed_word: preprocessed_word
+        validate_preprocessed preprocessed_word: preprocessed_word
+        validate_preprocessor preprocessed_word: preprocessed_word
+        validate_preprocessor_order preprocessed_word: preprocessed_word
+      end
+
+      def validation_error_message(object:, respond_to:)
+        "Argument preprocessed_word: does not respond to: #{object}#{respond_to}"
+      end
+
+      def validate_original_word(preprocessed_word:)
+        preprocessed_word_class = preprocessed_word.class
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#original_word') unless preprocessed_word.respond_to?(:original_word)
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#original_word=') unless preprocessed_word.respond_to?(:original_word=)
+      end
+
+      def validate_preprocessed_word(preprocessed_word:)
+        preprocessed_word_class = preprocessed_word.class
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessed_word') unless preprocessed_word.respond_to?(:preprocessed_word)
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessed_word=') unless preprocessed_word.respond_to?(:preprocessed_word=)
+      end
+
+      def validate_preprocessed(preprocessed_word:)
+        preprocessed_word_class = preprocessed_word.class
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessed') unless preprocessed_word.respond_to?(:preprocessed)
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessed=') unless preprocessed_word.respond_to?(:preprocessed=)
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessed?') unless preprocessed_word.respond_to?(:preprocessed?)
+      end
+
+      def validate_preprocessor(preprocessed_word:)
+        preprocessed_word_class = preprocessed_word.class
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessor') unless preprocessed_word.respond_to?(:preprocessor)
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessor=') unless preprocessed_word.respond_to?(:preprocessor=)
+      end
+
+      def validate_preprocessor_order(preprocessed_word:)
+        preprocessed_word_class = preprocessed_word.class
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessor_order') unless preprocessed_word.respond_to?(:preprocessor_order)
+        raise validation_error_message(object: preprocessed_word_class, respond_to: '#preprocessor_order=') unless preprocessed_word.respond_to?(:preprocessor_order=)
+      end
+    end
+    # rubocop: enable Layout/LineLength
+  end
+end

data/lib/LittleWeasel/preprocessors/preprocessed_words.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Preprocessors
+    # This class provides a container for Preprocessors::PreprocessedWord
+    # objects.
+    class PreprocessedWords
+      attr_reader :original_word
+      attr_accessor :preprocessed_words
+
+      # original_word:String the unsullied word before any preprocessing has
+      # been applied to it.
+      # preprocessed_words:Array, Preprocessors::PreprocessedWord, an Array
+      # of Preprocessors::PreprocessedWord objects that represents the
+      # original_word having passed through each successive
+      # Preprocessors::WordPreprocessor.
+      def initialize(original_word:, preprocessed_words:)
+        self.original_word = original_word
+        self.preprocessed_words = preprocessed_words
+      end
+
+      class << self
+        # Returns true if the word was passed through any preprocessing. If
+        # this is the case, #preprocessed_word may be different than
+        # #original_word.
+        def preprocessed?(preprocessed_words:)
+          # TODO: Do we need to check for preprocessors where
+          # #preprocessed? is true? or does preprocessed_words
+          # contain only preprocessed word objects where
+          # #preprocessed? is true?
+          preprocessed_words.present?
+        end
+
+        def preprocessed_word(preprocessed_words:)
+          return unless preprocessed? preprocessed_words: preprocessed_words
+
+          preprocessed_words.max_by(&:preprocessor_order).preprocessed_word
+        end
+      end
+
+      def preprocessed_word
+        self.class.preprocessed_word preprocessed_words: preprocessed_words
+      end
+
+      # Returns true if the word was preprocessed
+      def preprocessed?
+        self.class.preprocessed? preprocessed_words: preprocessed_words
+      end
+
+      private
+
+      attr_writer :original_word
+    end
+  end
+end

data/lib/LittleWeasel/preprocessors/preprocessed_words_validatable.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'preprocessed_word_validatable'
+
+module LittleWeasel
+  module Preprocessors
+    # This module provides methods to validate preprocessed words types.
+    # rubocop: disable Layout/LineLength
+    module PreprocessedWordsValidatable
+      module_function
+
+      def validate_prepreprocessed_words(preprocessed_words:)
+        raise ArgumentError, validation_error_message(object: preprocessed_words, respond_to: :original_word) unless preprocessed_words.respond_to? :original_word
+        raise ArgumentError, validation_error_message(object: preprocessed_words, respond_to: :preprocessed_words) unless preprocessed_words.respond_to? :preprocessed_words
+
+        preprocessed_words&.preprocessed_words&.each do |preprocessed_word|
+          PreprocessedWordValidatable.validate_prepreprocessed_word preprocessed_word: preprocessed_word
+        end
+      end
+
+      def validation_error_message(object:, respond_to:)
+        "Argument preprocessed_words does not respond to: #{object.class}##{respond_to}"
+      end
+    end
+    # rubocop: enable Layout/LineLength
+  end
+end

data/lib/LittleWeasel/preprocessors/word_preprocessable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'word_preprocessors_validatable'
+
+module LittleWeasel
+  module Preprocessors
+    # This module provides the word_preprocessors attribute for objects
+    # that support word preprocessors.
+    module WordPreprocessable
+      @word_preprocessors = []
+
+      attr_reader :word_preprocessors
+
+      private
+
+      attr_writer :word_preprocessors
+    end
+  end
+end

data/lib/LittleWeasel/preprocessors/word_preprocessor.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative '../errors/must_override_error'
+require_relative '../modules/class_name_to_symbol'
+require_relative '../modules/orderable'
+require_relative 'preprocessed_word'
+
+module LittleWeasel
+  module Preprocessors
+    # This is a base class that provides methods and functionality for
+    # word preprocessors. A "word preprocessor" is an object that manipulates a
+    # word before it is passed to any word filters and before it is compared
+    # against the dictionary for validity.
+    class WordPreprocessor
+      include Modules::ClassNameToSymbol
+      include Modules::Orderable
+
+      attr_reader :preprocessor_on
+
+      # order:Integer, the order in which this preprocessor should
+      # be applied.
+      # preprocessor_on:Boolean, whether or not this preprocessor
+      # should be applied to any words.
+      def initialize(order:)
+        validate_order order: order
+        self.order = order
+        preprocessor_on!
+      end
+
+      class << self
+        # Should return true if word matches the preprocess criteria;
+        # false, otherwise. If this preprocessor has no preprocess criteria,
+        # simply return true. This class method is unlike the instance method in
+        # that it does not consider whether or not this preprocessor is "on"
+        # or "off"; it simply returns true or false based on whether or not the
+        # word matches the preprocess criteria.
+        def preprocess?(_word)
+          true
+        end
+
+        # This method should UNconditionally apply preprocessing to word ONLY if
+        # word meets the criteria for preprocessing (.preprocess?).
+        #
+        # This method should return the following Array:
+        #
+        # [<preprocessed?>, <preprocessed word | nil>]
+        #
+        # Where:
+        #
+        #   <preprocessed?> == whether or not the word was preprocessed
+        #     based on whether or not the word meets the preprocessing
+        #     criteria (.preprocess?).
+        #
+        #   <preprocessed word | nil> == the preprocessed word (if word
+        #     met the preprocessing criteria (.preprocessed?)) or nil if
+        #     word was NOT preprocessed (word did NOT meet the preprocessing
+        #     criteria).
+        def preprocess(_word)
+          raise Errors::MustOverrideError
+        end
+      end
+
+      def preprocessor_on=(value)
+        raise ArgumentError, "Argument value is not true or false: #{value}" \
+          unless [true, false].include? value
+
+        @preprocessor_on = value
+      end
+
+      # Returns true if word meets the criteria for preprocessing. false
+      # is returned if word does not meet the criteria for preprocessing, or,
+      # if the preprocessor is "off".
+      def preprocess?(word)
+        return false if preprocessor_off?
+
+        self.class.preprocess? word
+      end
+
+      # Applies preprocessing to word if this preprocessor is "on" AND if word
+      # meets the criteria for preprocessing; no preprocessing is applied to
+      # word otherwise.
+      #
+      # This method should return a Preprocessors::PreprocessedWord object.
+      def preprocess(word)
+        preprocessed, preprocessed_word = if preprocessor_on?
+          self.class.preprocess word
+        else
+          [false, nil]
+        end
+        preprocessed_word(original_word: word, preprocessed_word: preprocessed_word, preprocessed: preprocessed)
+      end
+
+      # Returns true if this preprocessor is "on"; false, otherwise. If this
+      # preprocessor is "on", preprocessing should be applied to a word if word
+      # meets the criteria for preprocessing.
+      def preprocessor_on?
+        preprocessor_on
+      end
+
+      def preprocessor_on!
+        @preprocessor_on = true
+      end
+
+      # Returns true if this preprocessor is "off". Preprocessing should not
+      # be applied to a word if this preprocessor is "off".
+      def preprocessor_off?
+        !preprocessor_on?
+      end
+
+      def preprocessor_off!
+        @preprocessor_on = false
+      end
+
+      private
+
+      def preprocessed_word(original_word:, preprocessed:, preprocessed_word:)
+        PreprocessedWord.new(original_word: original_word, preprocessed: preprocessed,
+          preprocessed_word: preprocessed_word, preprocessor: to_sym, preprocessor_order: order)
+      end
+    end
+  end
+end