LittleWeasel 3.0.3 → 5.0.0

data/lib/LittleWeasel/metadata/invalid_words_metadata.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative '../modules/class_name_to_symbol'
+require_relative '../modules/configurable'
+require_relative '../modules/dictionary_cache_servicable'
+require_relative '../modules/dictionary_keyable'
+require_relative '../services/invalid_words_service'
+require_relative 'metadata_observerable'
+
+module LittleWeasel
+  module Metadata
+    # This class provides the ability to cache words not found in the
+    # associated dictionary.
+    class InvalidWordsMetadata
+      include Metadata::MetadataObserverable
+      include Modules::ClassNameToSymbol
+      include Modules::Configurable
+      include Modules::DictionaryCacheServicable
+      include Modules::DictionaryKeyable
+      include Modules::DictionaryMetadataServicable
+
+      delegate :on?, :off?, :value, :value_exceeded?,
+        :current_invalid_word_bytesize, :cache_invalid_words?,
+        to: :metadata
+
+      attr_reader :dictionary_metadata_object
+
+      def initialize(dictionary_metadata_object:, dictionary_metadata:,
+        dictionary_cache:, dictionary_key:, dictionary_words:)
+        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
+
+        unless dictionary_metadata_object.is_a? Observable
+          raise ArgumentError,
+            "Argument dictionary_metadata_object is not an Observable: #{dictionary_metadata_object.class}."
+        end
+
+        dictionary_metadata_object.add_observer self
+        self.dictionary_metadata_object = dictionary_metadata_object
+
+        unless dictionary_words.is_a? Hash
+          raise ArgumentError,
+            "Argument dictionary_words is not a Hash: #{dictionary_words.class}."
+        end
+
+        self.dictionary_words = dictionary_words
+      end
+
+      class << self
+        def metadata_key
+          to_sym
+        end
+
+        def observe?
+          config.max_invalid_words_bytesize?
+        end
+      end
+
+      # rubocop: disable Lint/UnusedMethodArgument
+      def init(params: nil)
+        dictionary_metadata_service.init(metadata_key: metadata_key)
+        self.metadata = Services::InvalidWordsService.new(dictionary_words).execute
+        self
+      end
+      # rubocop: enable Lint/UnusedMethodArgument
+
+      # rubocop: disable Lint/UnusedMethodArgument
+      def refresh(params: nil)
+        refresh_local_metadata
+        init unless metadata.present?
+        self
+      end
+      # rubocop: enable Lint/UnusedMethodArgument
+
+      # This method is called when a word is being searched in the
+      # dictionary.
+      def word_search(params:)
+        word_results = params[:word_results]
+
+        # TODO: NOW: Should we be returning #word_valid? or #success?
+        return word_results.word_valid? if word_results.word_cached?
+
+        # If we get here, we know that the word is NOT in the dictionary either
+        # as a valid word OR as a cached, INVALID word.
+
+        # If caching is supposed to take place, cache the word as invalid
+        # (not found).
+        word = word_results.preprocessed_word_or_original_word
+        dictionary_words[word] = false if cache_word? word
+        false
+      end
+
+      def update(action, params)
+        unless actions_whitelist.include? action
+          raise ArgumentError,
+            "Argument action is not in the actions_whitelist: #{action}"
+        end
+
+        send(action, params: params)
+        self
+      end
+
+      def actions_whitelist
+        %i[init refresh word_search]
+      end
+
+      private
+
+      attr_accessor :dictionary_words
+      attr_writer :dictionary_metadata_object
+
+      def cache_word?(word)
+        return false unless metadata.cache_invalid_words?
+
+        if metadata.value >= (word.bytesize + metadata.current_invalid_word_bytesize)
+          metadata.current_invalid_word_bytesize += word.bytesize
+          true
+        else
+          false
+        end
+      end
+
+      def update_dictionary_metadata(value:)
+        dictionary_metadata_service.set_dictionary_metadata(value: value, metadata_key: metadata_key)
+      end
+    end
+  end
+end

data/lib/LittleWeasel/metadata/invalid_words_service_results.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Metadata
+    # This class provides a container for the results of the
+    # InvalidWordsService service.
+    class InvalidWordsServiceResults
+      attr_accessor :current_invalid_word_bytesize
+      attr_reader :max_invalid_words_bytesize
+
+      def initialize(max_invalid_words_bytesize_on:,
+        current_invalid_word_bytesize:, max_invalid_words_bytesize:)
+
+        self.max_invalid_words_bytesize_on = max_invalid_words_bytesize_on
+        self.current_invalid_word_bytesize = current_invalid_word_bytesize
+        self.max_invalid_words_bytesize = max_invalid_words_bytesize
+      end
+
+      def on?
+        max_invalid_words_bytesize_on
+      end
+
+      def off?
+        !on?
+      end
+
+      def value
+        max_invalid_words_bytesize
+      end
+
+      def value_exceeded?
+        on? && current_invalid_word_bytesize > max_invalid_words_bytesize
+      end
+
+      def cache_invalid_words?
+        on? && !value_exceeded?
+      end
+
+      private
+
+      attr_accessor :max_invalid_words_bytesize_on
+      attr_writer :max_invalid_words_bytesize
+    end
+  end
+end

data/lib/LittleWeasel/metadata/metadata_observable_validatable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'metadata_observerable'
+
+module LittleWeasel
+  module Metadata
+    # This module provides methods to validate MetadataObservable objects.
+    module MetadataObservableValidatable
+      # This method validates a single MetadataObserverable object.
+      def validate_metadata_observable(metadata_observable)
+        unless valid_metadata_observable? metadata_observable
+          raise 'Argument metadata_observable is not a ' \
+            "Metadata::MetadataObserverable object: #{metadata_observable.class}"
+        end
+      end
+
+      def valid_metadata_observable?(metadata_observable)
+        metadata_observable.is_a? Metadata::MetadataObserverable
+      end
+    end
+  end
+end

data/lib/LittleWeasel/metadata/metadata_observerable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative '../errors/must_override_error'
+require_relative 'metadatable'
+
+module LittleWeasel
+  module Metadata
+    # Defines methods to support metadata modules that are observers of
+    # objects that include Metadata::DictionaryMetadata.
+    module MetadataObserverable
+      include Metadatable
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # class method inclusions for convenience.
+      module ClassMethods
+        # If the medatata observer is not in a state to observe, or is turned
+        # "off", return false; otherwise, return true...
+        #
+        # Configuration option settings may turn a metadata observer "off";
+        # for example, InvalidWordsMedata will not be observable unless
+        # LittleWeasel.configuration.max_invalid_words_bytesize? returns true.
+        #
+        # Other variables may also determine whether or not a metadata object is
+        # capable of observing; consequently, an instance-level #observe? method
+        # is also availble if this is the case (see below).
+        #
+        # If the observable state of your metadata object depends on
+        # configuration settings ALONE, return true/false using this class-level
+        # method, and do not override the instance-level #observe? method.
+        #
+        # If the observable state of your metadata object can only be determined
+        # AFTER the metadata object is instantiated: return true from the the
+        # class-level .observe? method; then, override the instance-level
+        # #observe? method and return true/false accordingly.
+        #
+        # If the observable state of your metadata object is determined by BOTH
+        # configuration settings AND variables that can only be determined AFTER
+        # the metadata object has been instantiated, use both the class-level
+        # and instance-level observe? to return true/false accordingly.
+        def observe?
+          false
+        end
+      end
+
+      # Return true/false depending on whether or not this metadata observer
+      # is in a state to observe.
+      #
+      # (See .observe? class-level method comments)
+      def observe?
+        self.class.observe?
+      end
+
+      # This is an override of Metadata#refresh_local_metadata. See
+      # Metadata#refresh_local_metadata comments.
+      def refresh_local_metadata
+        @metadata = dictionary_metadata_service.get_dictionary_metadata(metadata_key: metadata_key)
+      end
+
+      # This method receives notifications from an observable.
+      # object and should be chainable (return self).
+      # All actions should be filtered through the
+      # actions_whitelist and an error raised if action
+      # is not in the actions_whitelist. If **args are used,
+      # further filtering should be applied based on the
+      # need.
+      #
+      # @example
+      #
+      #  def update(action, **args)
+      #    raise ArgumentError unless actions_whitelist.include? action
+      #
+      #    send(action)
+      #    self
+      #  end
+      def update(_action, **_args)
+        raise Errors::MustOverrideError
+      end
+
+      # This method should return actions (messages) that can be sent
+      # to this object; for example, at a minimum :init and :refresh
+      # need to be in this list
+      def actions_whitelist
+        %i[init refresh]
+      end
+    end
+  end
+end

data/lib/LittleWeasel/metadata/metadatable.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative '../errors/must_override_error'
+require_relative '../services/dictionary_cache_service'
+
+module LittleWeasel
+  module Metadata
+    # This module defines methods to support objects that manage other objects
+    # that manage metadata related to a dictionary/ies.
+    # rubocop: disable Lint/UnusedMethodArgument, ignored - Methods in this
+    #          module need to keep their argument names because of specs.
+    module Metadatable
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # class method inclusions for convenience.
+      module ClassMethods
+        # Override this method to return the metadata key associated with this
+        # metadata object in the dictionary cache.
+        def metadata_key
+          to_sym
+        end
+      end
+
+      def metadata_key
+        self.class.metadata_key
+      end
+
+      # This method should UNCONDITIONALLY update the local metadata, using the
+      # metadata_key and notify all observers (if any) to initialize themselves
+      # as well.
+      #
+      # This method should be chainable (return self).
+      #
+      # @example
+      #
+      # . # Example of a root-level dictionary metadata object (e.g.
+      # . # Metadata::DictionaryMetadata)
+      #   def init(_params: nil)
+      #     self.metadata = {}
+      #     notify action: :init
+      #     refresh_local_metadata
+      #     unless count_observers.zero? || metadata.present?
+      #       raise 'Observers were called to #init but the dictionary cache metadata was not initialized'
+      #     end
+      #
+      #     self
+      #   end
+      #
+      # . # Example of a metadata observable object (e.g.
+      # . # Metadata::InvalidWords::InvalidWordsMetadata)
+      #   def init(params: nil)
+      #     self.metadata = Services::InvalidWordsService.new(dictionary_words).execute
+      #     self
+      #   end
+      def init(params: nil)
+        raise Errors::MustOverrideError
+      end
+
+      # This method should refresh the local metadata from the dictionary cache,
+      # if metadata exists in the dictionary cache for the given metatata_key.
+      # Otherwise, #init should be called to initialize this object.
+      # The idea is that metadata should be shared across metadata objects of
+      # the same type that use the same metadata_key.
+      #
+      # This method should be chainable (return self).
+      #
+      # @example
+      #
+      #   def refresh(params: nil)
+      #     refresh_local_metadata
+      #     init unless metadata.present?
+      #     self
+      #   end
+      def refresh(params: nil)
+        raise Errors::MustOverrideError
+      end
+
+      private
+
+      attr_reader :metadata
+
+      # This method should set the metadata in the dictionary cache, using the
+      # appropriate metadata key for this object (or nil if the root metadata
+      # object) AND set the @metadata local attribute so that a local copy is
+      # available for use.
+      #
+      # When instantiating this object, #init (see #init comments). If an
+      # updated copy of the metadata is needed #refresh (see comments) should
+      # be called.
+      #
+      # @example
+      #
+      #   def metadata=(value)
+      #     dictionary_cache_service = LittleWeasel::Services::DictionaryCacheService.new(
+      #       dictionary_key: dictionary_key, dictionary_cache: dictionary_cache)
+      #     dictionary_cache_service.dictionary_metadata_set(
+      #       metadata_key: METADATA_KEY, value: value)
+      #     @metadata = value
+      #   end
+      def metadata=(value)
+        @metadata = value
+        update_dictionary_metadata value: value
+      end
+
+      # This method updates the local metadata ONLY. Use this method if you
+      # need to update the local metadata from the dictionary cache metadata.
+      #
+      # Override this method in metadata observable classes as needed.
+      def refresh_local_metadata
+        @metadata = dictionary_metadata_service.dictionary_metadata
+      end
+
+      # This method should update the dictionary metadata for the the object
+      # when it is called.
+      #
+      # @example
+      #
+      #   def update_dictionary_metadata(value:)
+      #     dictionary_cache_service = LittleWeasel::Services::DictionaryCacheService.new(
+      #       dictionary_key: dictionary_key, dictionary_cache: dictionary_cache)
+      #     dictionary_cache_service.dictionary_metadata_set(
+      #       metadata_key: metadata_key, value: value)
+      #   end
+      # :reek:UnusedParameters, ignored - This method is meant to be called with the given argument and raises an
+      #   error if not overridden
+      def update_dictionary_metadata(value:)
+        raise Errors::MustOverrideError
+      end
+    end
+    # rubocop: enable Lint/UnusedMethodArgument
+  end
+end

data/lib/LittleWeasel/modules/class_name_to_symbol.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to convert the class name of the class
+    # mixing this module in to snake-case.
+    module ClassNameToSymbol
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # class method inclusions for convenience.
+      module ClassMethods
+        def to_sym
+          name.demodulize.underscore.to_sym
+        end
+      end
+
+      def to_sym
+        self.class.to_sym
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/configurable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides convienience methods for accessing this gem's
+    # configuration.
+    module Configurable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # class method inclusions for convenience.
+      module ClassMethods
+        def config
+          LittleWeasel.configuration
+        end
+      end
+
+      private
+
+      def config
+        @config ||= self.class.config
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/deep_dup.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module simply includes ActiveSupport's core for #deep_dup support. If
+    # we ever want to roll our own, we can do so here.
+    module DeepDup
+      require 'active_support/core_ext/object/deep_dup'
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_cache_keys.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods and constants used to define, initialize
+    # and manipulate a dictionary cache Hash object.
+    module DictionaryCacheKeys
+      DICTIONARY_CACHE = 'dictionary_cache'
+      DICTIONARY_REFERENCES = 'dictionary_references'
+      DICTIONARY_ID = 'dictionary_id'
+      DICTIONARIES = 'dictionaries'
+      SOURCE = 'source'
+      DICTIONARY_OBJECT = 'dictionary_object'
+
+      module_function
+
+      def initialize_dictionary_cache(dictionary_cache:)
+        dictionary_cache.each_key { |key| dictionary_cache.delete(key) }
+        dictionary_cache[DICTIONARY_CACHE] = initialized_dictionary_cache(include_root: false)
+        dictionary_cache
+      end
+
+      def initialized_dictionary_cache(include_root: true)
+        dictionary_cache = {
+          DICTIONARY_REFERENCES => {},
+          DICTIONARIES => {}
+        }
+        return { DICTIONARY_CACHE => dictionary_cache } if include_root
+
+        dictionary_cache
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_cache_servicable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../dictionary_key'
+require_relative '../services/dictionary_cache_service'
+require_relative 'dictionary_cache_validatable'
+
+module LittleWeasel
+  module Modules
+    # This module defines methods and attributes to consume the dictionary
+    # cache service.
+    module DictionaryCacheServicable
+      include DictionaryKeyable
+      include DictionaryCacheValidatable
+
+      attr_reader :dictionary_cache, :dictionary_key
+
+      def dictionary_cache_service
+        Services::DictionaryCacheService.new(dictionary_key: dictionary_key, dictionary_cache: dictionary_cache)
+      end
+
+      private
+
+      attr_writer :dictionary_cache, :dictionary_key
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_cache_validatable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Modules
+    # This module provides methods to validate a dictionary cache object.
+    # A dictionary cache object is a container that holds cached data
+    # related to one or more dictionaries. Dictionary cache objects are
+    # normally specific to a DictionaryManager object.
+    module DictionaryCacheValidatable
+      module_function
+
+      def validate_dictionary_cache(dictionary_cache:)
+        raise ArgumentError, "Argument dictionary_cache is not a valid Hash object: #{dictionary_cache.class}" \
+          unless dictionary_cache.is_a? Hash
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_creator_servicable.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../dictionary_key'
+require_relative '../services/dictionary_cache_service'
+require_relative '../filters/word_filters_validatable'
+
+module LittleWeasel
+  module Modules
+    # This module defines methods and attributes to consume the dictionary
+    # creator service.
+    module DictionaryCreatorServicable
+      include DictionaryKeyable
+      include Filters::WordFiltersValidatable
+
+      attr_reader :dictionary_cache, :dictionary_key, :word_filters
+
+      def dictionary_creator_service
+        Services::DictionaryCreatorService.new(dictionary_key: dictionary_key, dictionary_cache: dictionary_cache,
+          dictionary_metadata: dictionary_metadata, word_filters: word_filters)
+      end
+
+      private
+
+      attr_writer :dictionary_cache, :dictionary_key, :word_filters
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_file_loader.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../errors/dictionary_file_already_loaded_error'
+require_relative '../errors/dictionary_file_empty_error'
+require_relative '../errors/dictionary_file_not_found_error'
+require_relative '../errors/dictionary_file_too_large_error'
+
+module LittleWeasel
+  module Modules
+    # Defines methods to load dictionaries. The dictionary file path is used
+    # as a key to avoid loading the same dictionary multiple times.
+    module DictionaryFileLoader
+      def load(dictionary_file_path)
+        Loader.new(dictionary_file_path, config).load
+      end
+
+      # Helps with dictionary loading.
+      class Loader
+        def initialize(dictionary_file_path, config)
+          self.dictionary_file_path = dictionary_file_path
+          self.config = config
+        end
+
+        # Loads but DOES NOT update the dictionaries_hash. Use this if the dictionary
+        # DOES NOT need to hang around for any length of time.
+        def load
+          raise Errors::DictionaryFileNotFoundError unless file_exist?
+          raise Errors::DictionaryFileEmptyError if file_empty?
+          raise Errors::DictionaryFileTooLargeError if file_too_large?
+
+          load_dictionary
+        end
+
+        private
+
+        attr_accessor :config, :dictionary_file_path, :dictionary_words
+
+        def load_dictionary
+          prepare_dictionary(File.read(dictionary_file_path, mode: 'r')&.split)
+        end
+
+        def prepare_dictionary(words)
+          words&.uniq!&.compact!
+          words if words.present?
+        end
+
+        def file_size
+          # File.size? returns nil if file_name doesn't exist or has zero size,
+          # the size of the file otherwise.
+          @file_size ||= File.size?(dictionary_file_path) || 0
+        end
+
+        def file_exist?
+          @file_exist ||= File.exist? dictionary_file_path
+        end
+
+        def file_empty?
+          @file_empty ||= file_exist? && file_size.zero?
+        end
+
+        def file_too_large?
+          @file_too_large ||= file_exist? && file_size > config.max_dictionary_file_bytes
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/modules/dictionary_key_validatable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../dictionary_key'
+
+module LittleWeasel
+  module Modules
+    # Provides methods to validate a dictionary key object.
+    module DictionaryKeyValidatable
+      module_function
+
+      def validate_dictionary_key(dictionary_key:)
+        raise ArgumentError, "Argument dictionary_key is not a valid DictionaryKey object: #{dictionary_key.class}" \
+          unless dictionary_key.is_a? DictionaryKey
+      end
+    end
+  end
+end