LittleWeasel 3.0.4 → 4.0.0

data/lib/LittleWeasel/preprocessors/word_preprocessor_managable.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'word_preprocessable'
+require_relative 'word_preprocessor_validatable'
+
+module LittleWeasel
+  module Preprocessors
+    # This module provides methods and functionality to manage 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.
+    #
+    # When creating your own word preprocessors, here are some things you
+    # need to consider:
+    #
+    # Multiple word preprocessors can be applied to a given word. Word
+    # processors will be applied to a word in
+    # Preprocessors::WordPreprocessor#order order (ascending). Even though this
+    # is the case, it doesn't mean you should seek to apply more than one word
+    # preprocessor at a time. However, if you do, write and order your word
+    # preprocessors in such a way that each preprocessor manipulates the word
+    # in a complimentary rather than contridictionary way. For example,
+    # applying one word preprocessor that convert a word to uppercase and a
+    # second that converts the word to lowercase, contradict each other.
+    #
+    # Another thing you need to consider, is whether or not metadata observers
+    # should be notified of the preprocessed word (now that it has been
+    # potentially manipulated) or if they should be notified of the original
+    # word; this is because, the original word may not be found as a valid word
+    # in the dictionary, while the preprocessed word might and vise versa.
+    module WordPreprocessorManagable
+      include WordPreprocessable
+      include WordPreprocessorsValidatable
+
+      # Override attr_reader word_preprocessor found in WordPreprocessable
+      # so that we don't raise nil errors when using word_preprocessors.
+      def word_preprocessors
+        @word_preprocessors ||= []
+      end
+
+      def clear_preprocessors
+        self.word_preprocessors = []
+      end
+
+      # Appends word preprocessors to the #word_preprocessors Array.
+      #
+      # If Argument word_preprocessor is nil, a block must be passed to populate
+      # the word_preprocessors with an Array of valid word preprocessor objects.
+      #
+      # This method is used for adding/appending word preprocessors to the
+      # word_preprocessors Array. To replace word preprocessors, use #replace_preprocessors;
+      # to perform any other manipulation of the word_preprocessors Array,
+      # use #word_preprocessors directly.
+      def add_preprocessors(word_preprocessors: nil)
+        return if word_preprocessors.is_a?(Array) && word_preprocessors.blank?
+
+        unless word_preprocessors.present? || block_given?
+          raise 'A block is required if argument word_preprocessors is nil'
+        end
+
+        word_preprocessors ||= []
+        yield word_preprocessors if block_given?
+
+        concat_and_sort_word_preprocessors! word_preprocessors
+      end
+      alias append_preprocessors add_preprocessors
+
+      def replace_preprocessors(word_preprocessors:)
+        clear_preprocessors
+        add_preprocessors word_preprocessors: word_preprocessors
+      end
+
+      def preprocessors_on=(on)
+        raise ArgumentError, "Argument on is not true or false: #{on.class}" unless [true, false].include?(on)
+
+        word_preprocessors.each { |word_preprocessor| word_preprocessor.preprocessor_on = on }
+      end
+
+      # Returns a Preprocessors::PreprocessedWords object.
+      def preprocess(word:)
+        preprocessed_words = preprocessed_words word: word
+        PreprocessedWords.new(original_word: word, preprocessed_words: preprocessed_words)
+      end
+
+      def preprocessed_words(word:)
+        word_preprocessors.map do |word_preprocessor|
+          word_preprocessor.preprocess(word).tap do |processed_word|
+            word = processed_word.preprocessed_word
+          end
+        end
+      end
+
+      # Returns the final (or last) preprocessed word in the Array of
+      # preprocessed words. The final preprocessed word is the word that has
+      # passed through all the word preprocessors.
+      def preprocessed_word(word:)
+        preprocessed_words = self.preprocessed_words word: word
+        preprocessed_words.max_by(&:preprocessor_order).preprocessed_word unless preprocessed_words.blank?
+      end
+
+      private
+
+      # This method concatinates preprocessors to #word_preprocessors,
+      # sorts #word_preprocessors by WordPreprocessor#order and
+      # returns the results.
+      def concat_and_sort_word_preprocessors!(preprocessors)
+        validate_word_preprocessors word_preprocessors: preprocessors
+
+        word_preprocessors.concat preprocessors
+        word_preprocessors.sort_by!(&:order)
+      end
+    end
+  end
+end

data/lib/LittleWeasel/preprocessors/word_preprocessor_validatable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Preprocessors
+    # This module validates word preprocessor types.
+    # rubocop: disable Layout/LineLength
+    module WordPreprocessorValidatable
+      module_function
+
+      # :reek:ManualDispatch - ignored, this is duck-typing not 'simulated polymorphism'
+      # :reek:TooManyStatements - ignored, "too many statements" is easier to understand than arbitrarily breaking all this down into individual methods
+      def validate_word_preprocessor(word_preprocessor:)
+        # You can use your own word preprocessor types as long as they quack
+        # correctly; however, you are responsible for the behavior of these
+        # required methods/ attributes. It's probably better to follow the
+        # pattern of existing word preprocessor objects and inherit from
+        # Preprocessors::WordPreprocessor.
+
+        word_preprocessor_class = word_preprocessor.class
+
+        # class methods
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '.preprocess') unless word_preprocessor_class.respond_to?(:preprocess)
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '.preprocess?') unless word_preprocessor_class.respond_to?(:preprocess?)
+
+        # instance methods
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '#preprocess') unless word_preprocessor.respond_to?(:preprocess)
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '#preprocess?') unless word_preprocessor.respond_to?(:preprocess?)
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '#preprocessor_off?') unless word_preprocessor.respond_to?(:preprocessor_off?)
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '#preprocessor_on') unless word_preprocessor.respond_to?(:preprocessor_on)
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '#preprocessor_on=') unless word_preprocessor.respond_to?(:preprocessor_on=)
+        raise validation_error_message(object: word_preprocessor_class, respond_to: '#preprocessor_on?') unless word_preprocessor.respond_to?(:preprocessor_on?)
+      end
+
+      def validation_error_message(object:, respond_to:)
+        "Argument word_preprocessor: does not respond to: #{object}#{respond_to}"
+      end
+    end
+    # rubocop: enable Layout/LineLength
+  end
+end

data/lib/LittleWeasel/preprocessors/word_preprocessors_validatable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'word_preprocessor_validatable'
+
+module LittleWeasel
+  module Preprocessors
+    # This module provides methods to validate an Array of word preprocessor
+    # objects.
+    module WordPreprocessorsValidatable
+      module_function
+
+      def validate_word_preprocessors(word_preprocessors:)
+        return if word_preprocessors.blank?
+
+        raise ArgumentError, "Argument word_preprocessors is not an Array: #{word_preprocessors.class}" \
+          unless word_preprocessors.is_a? Array
+
+        word_preprocessors.each do |word_preprocessor|
+          WordPreprocessorValidatable.validate_word_preprocessor word_preprocessor: word_preprocessor
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/services/dictionary_cache_service.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require_relative '../modules/dictionary_cache_keys'
+require_relative '../modules/dictionary_cache_validatable'
+require_relative '../modules/dictionary_keyable'
+require_relative '../modules/dictionary_sourceable'
+require_relative '../modules/dictionary_validatable'
+
+module LittleWeasel
+  module Services
+    # This class provides methods and attributes that can be used to manage the
+    # dictionary cache. The "dictionary cache" is a simple Hash that provides
+    # access to informaiton related to dictionaries through a dictionary "key".
+    # A dictionary "key" is a unique key comprised of a locale and
+    # optional "tag" (see Modules::Taggable and DictionaryKey for more
+    # information). The dictionary cache also provides a way for dictionary
+    # objects to share dictionary information, in particular, the dictionary
+    # file and dictionary metadata.
+    class DictionaryCacheService
+      include Modules::DictionaryKeyable
+      include Modules::DictionaryCacheValidatable
+      include Modules::DictionaryCacheKeys
+      include Modules::DictionarySourceable
+      include Modules::DictionaryValidatable
+
+      attr_reader :dictionary_cache
+
+      # This class produces the following (example) Hash that represents the
+      # dictionary cache structure:
+      #
+      # @example This is an example:
+      #
+      # {
+      #   'dictionary_cache' =>
+      #   {
+      #     'dictionary_references' =>
+      #     {
+      #       'en' =>
+      #       {
+      #         'dictionary_id' => 19ec7845
+      #       },
+      #       'en-US' =>
+      #       {
+      #         'dictionary_id' => 0987a3f2
+      #       },
+      #       'en-US-temp' =>
+      #       {
+      #         'dictionary_id' => 9273eac6
+      #       }
+      #     },
+      #     'dictionaries' =>
+      #     {
+      #       19ec7845 =>
+      #         {
+      #           'source' => '/en.txt',
+      #           'dictionary_object' => {}
+      #         },
+      #       0987a3f2 =>
+      #         {
+      #           'source' => '/en-US.txt',
+      #           'dictionary_object' => {}
+      #         },
+      #       9273eac6 =>
+      #         {
+      #           'source' => '*736ed423',
+      #           'dictionary_object' => {}
+      #         }
+      #     }
+      #   }
+      # }
+      def initialize(dictionary_key:, dictionary_cache:)
+        validate_dictionary_key dictionary_key: dictionary_key
+        self.dictionary_key = dictionary_key
+
+        validate_dictionary_cache dictionary_cache: dictionary_cache
+        self.dictionary_cache = dictionary_cache
+
+        self.class.init(dictionary_cache: dictionary_cache) unless dictionary_cache[DICTIONARY_CACHE]
+      end
+
+      class << self
+        # This method resets dictionary_cache to its initialized state.
+        # This class method is different from the #init instance method
+        # in that ALL dictionary references and ALL dictionaries are
+        # initialized.
+        def init(dictionary_cache:)
+          Modules::DictionaryCacheKeys.initialize_dictionary_cache dictionary_cache: dictionary_cache
+        end
+
+        # Returns true if the dictionary cache is initialized; that
+        # is, if the given dictionary_cache is in the same state the
+        # dictionary cache would be in after .init were called.
+        def init?(dictionary_cache:)
+          initialized_dictionary_cache = init(dictionary_cache: {})
+          dictionary_cache.eql?(initialized_dictionary_cache)
+        end
+
+        # Returns the number of dictionaries currently in the cache.
+        def count(dictionary_cache:)
+          dictionary_cache.dig(self::DICTIONARY_CACHE, self::DICTIONARIES)&.keys&.count || 0
+        end
+      end
+
+      # This method resets the dictionary cache for the given key. This method
+      # is different from the .init class method in that ONLY the dictionary
+      # reference and dictionary specific to the given key is initialized.
+      def init
+        # TODO: Do not delete the dictionary if it is being pointed to by
+        # another dictionary reference.
+        dictionary_cache_hash = dictionary_cache[DICTIONARY_CACHE]
+        dictionary_cache_hash[DICTIONARIES]&.delete(dictionary_id)
+        dictionary_cache_hash[DICTIONARY_REFERENCES]&.delete(key)
+        self
+      end
+
+      # Returns true if the dictionary reference exists for the given key; false
+      # otherwise. This method is only concerned with the dictionary reference
+      # and has nothing to do with whether or not the associated dictionary
+      # is actually loaded into the dictionary cache.
+      def dictionary_reference?
+        dictionary_reference&.present? || false
+      end
+
+      # Returns true if a dictionaries Hash key exists for the given dictionary_id
+      # in the dictionary cache. This method is only concerned with the existance of
+      # the key and has nothing to do with whether or not file/memory sources are
+      # present or the presence of a dictionary object.
+      def dictionary?
+        dictionary_cache[DICTIONARY_CACHE][DICTIONARIES].key? dictionary_id
+      end
+
+      # 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(source:)
+        validate_dictionary_source_does_not_exist dictionary_cache_service: self
+
+        dictionary_id = dictionary_id_for_dictionary_source(source: source)
+        self.dictionary_reference = dictionary_id
+        # 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.
+        self.dictionary_source = source unless dictionary?
+        self
+      end
+
+      # Returns the dictionary id if there is a dictionary id in the dictionary
+      # cache associated with the given key; nil otherwise.
+      def dictionary_id
+        dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARY_REFERENCES, key, DICTIONARY_ID)
+      end
+
+      # Returns the dictionary id if there is a dictionary id in the dictionary
+      # cache associated with the given key. This method raises an error if the
+      # dictionary id cannot be found.
+      def dictionary_id!
+        return dictionary_id if dictionary_id?
+
+        raise ArgumentError, "A dictionary id could not be found for key '#{key}'."
+      end
+
+      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!
+
+      def dictionary_source
+        dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARIES, dictionary_id, SOURCE)
+      end
+      alias dictionary_file dictionary_source
+
+      # This method returns true if the dictionary associated with the
+      # given dictionary key is loaded/cached. If this is the case,
+      # a dictionary object is available in the dictionary cache.
+      def dictionary_object?
+        dictionary_object.present?
+      end
+      alias dictionary_exists? dictionary_object?
+
+      # Returns the dictionary object from the dictionary cache for the given
+      # key. This method raises an error if the dictionary is not in the cache;
+      # that is, if the dictionary was not previously loaded from disk or memory.
+      def dictionary_object!
+        unless dictionary_object?
+          raise ArgumentError,
+            "The dictionary object associated with argument key '#{key}' is not in the cache."
+        end
+
+        dictionary_object
+      end
+
+      def dictionary_object
+        dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARIES, dictionary_id, DICTIONARY_OBJECT)
+      end
+
+      def dictionary_object=(object)
+        raise ArgumentError, 'Argument object is not a Dictionary object' unless object.is_a? Dictionary
+
+        unless dictionary_reference?
+          raise ArgumentError,
+            "The dictionary reference associated with key '#{key}' could not be found."
+        end
+        return if object.equal? dictionary_object
+
+        if dictionary_exists?
+          raise ArgumentError,
+            "The dictionary is already loaded/cached for key '#{key}'; use #unload or #kill first."
+        end
+
+        dictionary_cache[DICTIONARY_CACHE][DICTIONARIES][dictionary_id!][DICTIONARY_OBJECT] = object
+      end
+
+      private
+
+      attr_writer :dictionary_cache
+
+      def dictionary_reference
+        dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARY_REFERENCES, key)
+      end
+
+      def dictionary_reference=(dictionary_id)
+        dictionary_cache[DICTIONARY_CACHE][DICTIONARY_REFERENCES][key] = {
+          DICTIONARY_ID => dictionary_id
+        }
+      end
+
+      # Returns the dictionary_id for the source if it exists in dictionaries;
+      # otherwise, returns the new dictionary id that should be used.
+      def dictionary_id_for_dictionary_source(source:)
+        dictionary_source?(source: source) || SecureRandom.uuid[0..7]
+      end
+
+      # Returns the dictionary_id associated with source if source exists;
+      # nil otherwise.
+      def dictionary_source?(source:)
+        dictionaries = dictionary_cache.dig(DICTIONARY_CACHE, DICTIONARIES)
+        dictionaries&.each_pair do |dictionary_id, dictionary_hash|
+          return dictionary_id if source == dictionary_hash[SOURCE]
+        end
+        nil
+      end
+
+      def dictionary_source=(source)
+        dictionary_cache[DICTIONARY_CACHE][DICTIONARIES][dictionary_id!] = {
+          SOURCE => source,
+          DICTIONARY_OBJECT => {}
+        }
+      end
+
+      def dictionary_id?
+        dictionary_id.present?
+      end
+    end
+  end
+end

data/lib/LittleWeasel/services/dictionary_creator_service.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative '../dictionary'
+require_relative '../filters/word_filterable'
+require_relative '../filters/word_filters_validatable'
+require_relative '../metadata/dictionary_metadata'
+require_relative '../modules/dictionary_cache_servicable'
+require_relative '../modules/dictionary_creator_servicable'
+require_relative '../modules/dictionary_keyable'
+require_relative '../modules/dictionary_metadata_servicable'
+require_relative '../modules/dictionary_sourceable'
+require_relative '../preprocessors/word_preprocessor_managable'
+require_relative 'dictionary_file_loader_service'
+
+module LittleWeasel
+  module Services
+    # This class provides a service to load dictionaries from disk, create
+    # and return a Dictionary object.
+    class DictionaryCreatorService
+      include Filters::WordFilterable
+      include Filters::WordFiltersValidatable
+      include Modules::DictionaryCacheServicable
+      include Modules::DictionaryKeyable
+      include Modules::DictionaryMetadataServicable
+      include Modules::DictionarySourceable
+      include Preprocessors::WordPreprocessorManagable
+
+      def initialize(dictionary_key:, dictionary_cache:, dictionary_metadata:,
+        word_filters: nil, word_preprocessors: nil)
+        validate_dictionary_key dictionary_key: dictionary_key
+        self.dictionary_key = dictionary_key
+
+        validate_dictionary_cache dictionary_cache: dictionary_cache
+        self.dictionary_cache = dictionary_cache
+
+        validate_dictionary_metadata dictionary_metadata: dictionary_metadata
+        self.dictionary_metadata = dictionary_metadata
+
+        validate_word_filters word_filters: word_filters unless word_filters.blank?
+        self.word_filters = word_filters
+
+        validate_word_preprocessors word_preprocessors: word_preprocessors unless word_preprocessors.blank?
+        self.word_preprocessors = word_preprocessors
+      end
+
+      def from_file_source(file:)
+        add_dictionary_file_source file: file
+        dictionary_words = dictionary_file_loader_service.execute
+        create_dictionary dictionary_words: dictionary_words
+      end
+
+      def from_memory_source(dictionary_words:)
+        add_dictionary_memory_source
+        create_dictionary dictionary_words: dictionary_words
+      end
+
+      private
+
+      def dictionary_file_loader_service
+        Services::DictionaryFileLoaderService.new dictionary_key: dictionary_key, dictionary_cache: dictionary_cache
+      end
+
+      def create_dictionary(dictionary_words:)
+        Dictionary.new(dictionary_key: dictionary_key, dictionary_cache: dictionary_cache,
+          dictionary_metadata: dictionary_metadata, dictionary_words: dictionary_words, word_filters: word_filters,
+          word_preprocessors: word_preprocessors).tap do |dictionary|
+          dictionary_cache_service.dictionary_object = dictionary
+        end
+      end
+
+      # Adds a dictionary file source. A "file source" is a file path that
+      # indicates that the dictionary words associated with this dictionary are
+      # located on disk. This file path is used to locate and load the
+      # dictionary words into the dictionary cache for use.
+      #
+      # @param file [String] a file path pointing to the dictionary file to load and use.
+      #
+      # @return returns a reference to self.
+      def add_dictionary_file_source(file:)
+        dictionary_cache_service.add_dictionary_source(source: file)
+      end
+
+      # Adds a dictionary memory source. A "memory source" indicates that the
+      # dictionary words associated with this dictionary were created
+      # dynamically and will be located in memory, as opposed to loaded from
+      # a file on disk.
+      #
+      # @return returns a reference to self.
+      def add_dictionary_memory_source
+        dictionary_cache_service.add_dictionary_source(source: memory_source)
+      end
+    end
+  end
+end