LittleWeasel 3.0.3 → 5.0.0

data/lib/LittleWeasel/modules/dictionary_keyable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+require_relative 'dictionary_key_validatable'
+
+module LittleWeasel
+  module Modules
+    # This module defines attributes and functionality for a dictionary
+    # key. A dictionary key is a unique key (basically a locale and optional
+    # tag suffix) that is used to link a dictionary to the dictionary cache
+    # and dictionary metadata objects.
+    module DictionaryKeyable
+      include Modules::DictionaryKeyValidatable
+
+      attr_reader :dictionary_key
+
+      delegate :key, to: :dictionary_key
+
+      private
+
+      attr_writer :dictionary_key
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_metadata_servicable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../dictionary_key'
+require_relative '../services/dictionary_metadata_service'
+require_relative 'dictionary_cache_validatable'
+require_relative 'dictionary_metadata_validatable'
+
+module LittleWeasel
+  module Modules
+    # This module defines methods and attributes to consume the dictionary
+    # metadata service.
+    module DictionaryMetadataServicable
+      include DictionaryKeyable
+      include DictionaryCacheValidatable
+      include DictionaryMetadataValidatable
+
+      attr_reader :dictionary_cache, :dictionary_key, :dictionary_metadata
+
+      def dictionary_metadata_service
+        Services::DictionaryMetadataService.new(dictionary_key: dictionary_key, dictionary_cache: dictionary_cache,
+          dictionary_metadata: dictionary_metadata)
+      end
+
+      private
+
+      attr_writer :dictionary_cache, :dictionary_key, :dictionary_metadata
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_metadata_validatable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a dictionary metadata object.
+    module DictionaryMetadataValidatable
+      module_function
+
+      def validate_dictionary_metadata(dictionary_metadata:)
+        raise ArgumentError, "Argument dictionary_metadata is not a valid Hash object: #{dictionary_metadata.class}" \
+          unless dictionary_metadata.is_a? Hash
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_source_validatable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a dictionary source.
+    module DictionarySourceValidatable
+      module_function
+
+      def validate_dictionary_source(dictionary_source:)
+        raise ArgumentError, 'Argument dictionary_source is not present' \
+          unless dictionary_source.present?
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_sourceable.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative '../modules/dictionary_cache_keys'
+require_relative '../modules/dictionary_source_validatable'
+require_relative '../modules/dictionary_validatable'
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to manage dictionary sources.
+    module DictionarySourceable
+      include Modules::DictionaryCacheKeys
+      include Modules::DictionarySourceValidatable
+      include Modules::DictionaryValidatable
+
+      MEMORY_SOURCE = '*'
+
+      def self.file_source?(dictionary_source)
+        !memory_source? dictionary_source
+      end
+
+      def self.memory_source?(dictionary_source)
+        dictionary_source =~ /^#{Regexp.quote(MEMORY_SOURCE)}[0-9a-fA-F]{8}$/
+      end
+
+      def memory_source
+        "#{MEMORY_SOURCE}#{SecureRandom.uuid[0..7]}"
+      end
+      module_function :memory_source
+
+      # Adds a dictionary source. A "dictionary source" specifies the source from which
+      # the dictionary ultimately obtains its words.
+      #
+      # @param source [String] the dictionary source. This can be a file path
+      # or a memory source indicator to signify that the dictionary was created
+      # dynamically from memory.
+      def add_dictionary_source(dictionary_source:)
+        validate_dictionary_source_does_not_exist dictionary_cache_service: self
+
+        set_dictionary_reference \
+          dictionary_id: dictionary_id_associated_with(dictionary_source: dictionary_source)
+        # Only set the dictionary source if it doesn't already exist because settings
+        # the dictionary source wipes out the #dictionary_object; dictionary objects
+        # can have more than one dictionary reference pointing to them, and we don't
+        # want to blow away the #dictionary_object, metadata, or any other data
+        # associated with it if it already exists.
+        set_dictionary_source(dictionary_source: dictionary_source) unless dictionary?
+        self
+      end
+
+      def dictionary_source
+        dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARIES, dictionary_id, SOURCE)
+      end
+      alias dictionary_file dictionary_source
+
+      def dictionary_source!
+        raise ArgumentError, "A dictionary source could not be found for key '#{key}'." \
+          unless dictionary_reference?
+
+        dictionary_cache[DICTIONARY_CACHE][DICTIONARIES][dictionary_id!][SOURCE]
+      end
+      alias dictionary_file! dictionary_source!
+
+      private
+
+      # Sets the dictionary source in the dictionary cache.
+      def set_dictionary_source(dictionary_source:)
+        dictionary_cache[DICTIONARY_CACHE][DICTIONARIES][dictionary_id!] = {
+          SOURCE => dictionary_source,
+          DICTIONARY_OBJECT => {}
+        }
+      end
+
+      # Returns the dictionary_id for the dictionary_source if it exists in
+      # dictionaries; otherwise, returns the new dictionary id that should
+      # be used.
+      def dictionary_id_associated_with(dictionary_source:)
+        dictionaries = dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARIES)
+        dictionaries&.each_pair do |dictionary_id, dictionary_hash|
+          return dictionary_id if dictionary_source == dictionary_hash[SOURCE]
+        end
+        SecureRandom.uuid[0..7]
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_validatable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides validations related to dictionaries in
+    # the dictionary cache.
+    module DictionaryValidatable
+      module_function
+
+      def validate_dictionary_source_does_not_exist(dictionary_cache_service:)
+        # If a dictionary_reference exists, the dictionary_source must exist.
+        if dictionary_cache_service.dictionary_reference?
+          raise "The dictionary source associated with key '#{dictionary_cache_service.key}' already exists."
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/language.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+
+module LittleWeasel
+  module Modules
+    # Provides methods for normalizing language for a locale.
+    module Language
+      def language?
+        language.present?
+      end
+
+      def normalize_language!
+        self.language = normalize_language language
+      end
+
+      module_function
+
+      def normalize_language(language)
+        language&.downcase
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/language_validatable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a language.
+    module LanguageValidatable
+      module_function
+
+      def validate_language(language:)
+        raise ArgumentError, "Argument language '#{language}' is not a Symbol." unless language.is_a? Symbol
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/locale.rb

@@ -0,0 +1,23 @@
+# 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
+      include Language
+      include Region
+
+      def locale
+        language = normalize_language self.language
+        return language.to_s unless region?
+
+        region = normalize_region self.region
+        "#{language}-#{region}"
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/order_validatable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a value that can be used
+    # in sorting.
+    module OrderValidatable
+      module_function
+
+      def validate_order(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
+    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,24 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/blank'
+
+module LittleWeasel
+  module Modules
+    # Provides methods for normalizing a region for a locale.
+    module Region
+      def region?
+        region.present?
+      end
+
+      def normalize_region!
+        self.region = normalize_region region
+      end
+
+      module_function
+
+      def normalize_region(region)
+        region&.upcase
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/region_validatable.rb

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

data/lib/LittleWeasel/modules/tag_validatable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a tag.
+    module TagValidatable
+      module_function
+
+      def validate_tag(tag:)
+        raise ArgumentError, "Argument tag '#{tag}' is not a Symbol." unless tag.blank? || tag.is_a?(Symbol)
+      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,29 @@
+# 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.
+    # :reek:Attribute, ignored - Fixing this would result in nothing but trivial setter methods
+    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,56 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Preprocessors
+    # This module provides functionality that validates preprocessed word types.
+    # rubocop: disable Layout/LineLength
+    # :reek:ManualDispatch, ignored - these methods are raising errors, not performing conditional code execution
+    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,59 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Preprocessors
+    # This class provides a container for Preprocessors::PreprocessedWord
+    # objects.
+    class PreprocessedWords
+      attr_reader :original_word, :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_words=(value)
+        value ||= []
+        @preprocessed_words = value
+      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,28 @@
+# 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
+
+      # :reek:ManualDispatch, ignored - this is raising an error, not conditional code execution
+      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