LittleWeasel 3.0.4 → 4.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,136 @@
+# 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.
+    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
+      #
+      # rubocop: disable Lint/UnusedMethodArgument
+      def init(params: nil)
+        raise Errors::MustOverrideError
+      end
+      # rubocop: enable Lint/UnusedMethodArgument
+
+      # 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
+      # rubocop: disable Lint/UnusedMethodArgument
+      def refresh(params: nil)
+        raise Errors::MustOverrideError
+      end
+      # rubocop: enable Lint/UnusedMethodArgument
+
+      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
+      # rubocop: disable Lint/UnusedMethodArgument
+      def update_dictionary_metadata(value:)
+        raise Errors::MustOverrideError
+      end
+      # rubocop: enable Lint/UnusedMethodArgument
+    end
+  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