LittleWeasel 3.0.4 → 4.0.0

data/lib/LittleWeasel/errors/dictionary_file_empty_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Errors
+    # This class describes an error when a dictionary file is zero bytes.
+    class DictionaryFileEmptyError < StandardError; end
+  end
+end

data/lib/LittleWeasel/errors/dictionary_file_not_found_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Errors
+    # This class describes an error when a dictionary file is not found.
+    class DictionaryFileNotFoundError < StandardError; end
+  end
+end

data/lib/LittleWeasel/errors/dictionary_file_too_large_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Errors
+    # This class describes an error when a the dictionary file is too large.
+    class DictionaryFileTooLargeError < StandardError
+      def initialize(msg: nil)
+        unless msg.present?
+          msg = 'The dictionary file size is larger than ' \
+            "max_dictionary_file_megabytes: #{LittleWeasel.configuration.max_dictionary_file_megabytes}"
+        end
+        super msg
+      end
+    end
+  end
+end

data/lib/LittleWeasel/errors/language_required_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Errors
+    # This class describes an error when a language is required but was missing.
+    class LanguageRequiredError < StandardError; end
+  end
+end

data/lib/LittleWeasel/errors/must_override_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Errors
+    # This class describes an error when the method must be overridden.
+    class MustOverrideError < StandardError; end
+  end
+end

data/lib/LittleWeasel/filters/en_us/currency_filter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../../errors/must_override_error'
+require_relative '../word_filter'
+
+module LittleWeasel
+  module Filters
+    module EnUs
+      # This class represents a currency filter.
+      class CurrencyFilter < WordFilter
+        class << self
+          def filter_match?(word)
+            /^[-+]?\$[[:digit:]]{1,3}(?:,?[[:digit:]]{3})*(?:\.[[:digit:]]{2})?$/.match? word.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/filters/en_us/numeric_filter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../../errors/must_override_error'
+require_relative '../word_filter'
+
+module LittleWeasel
+  module Filters
+    module EnUs
+      # This class represents a numeric filter.
+      class NumericFilter < WordFilter
+        class << self
+          def filter_match?(word)
+            /^[-+]?[[:digit:]]{1,3}(?:,?[[:digit:]]{3})*(?:\.[[:digit:]]{1,2})?$/.match? word.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/filters/en_us/single_character_word_filter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../../errors/must_override_error'
+require_relative '../word_filter'
+
+module LittleWeasel
+  module Filters
+    module EnUs
+      # This class represents a filter for single character words.
+      class SingleCharacterWordFilter < WordFilter
+        class << self
+          def filter_match?(word)
+            return false unless word.is_a? String
+
+            /^[aAI]{1}$/.match? word.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/LittleWeasel/filters/word_filter.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../errors/must_override_error'
+require_relative '../modules/class_name_to_symbol'
+
+module LittleWeasel
+  module Filters
+    # This module provides methods/functionality for filtering dictionary words.
+    class WordFilter
+      include Modules::ClassNameToSymbol
+
+      attr_reader :filter_on
+
+      def initialize
+        filter_on!
+      end
+
+      class << self
+        # Should return true if this word matches the filter criteria; false,
+        # otherwise. This class method is unlike the instance method in that it
+        # does not consider whether or not this filter is "on" or "off"; it
+        # simply returns true or false based on whether or not the word matches
+        # the filter.
+        def filter_match?(_word)
+          raise Errors::MustOverrideError
+        end
+      end
+
+      def filter_on=(value)
+        raise ArgumentError, "Argument value is not true or false: #{value.class}" \
+          unless [true, false].include? value
+
+        @filter_on = value
+      end
+
+      def filter_match?(word)
+        return false if filter_off?
+
+        self.class.filter_match? word
+      end
+
+      def filter_on!
+        self.filter_on = true
+      end
+
+      def filter_off!
+        self.filter_on = false
+      end
+
+      def filter_on?
+        filter_on
+      end
+
+      def filter_off?
+        !filter_on?
+      end
+    end
+  end
+end

data/lib/LittleWeasel/filters/word_filter_managable.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'word_filterable'
+require_relative 'word_filters_validatable'
+
+module LittleWeasel
+  module Filters
+    # This module provides methods/functionality to manage word filters.
+    # Word fliters are processes through which words are passed; if the
+    # process returns true, the word should be considered valid and all
+    # subsequent filters ignored; if the process returns false, the word
+    # should be passed to the next filter, and so on. When using word
+    # filters, you need to consider whether or not metadata observers
+    # should be notified of the word now that it is considered "valid"
+    # although may not literally be a valid word in the dictionary.
+    module WordFilterManagable
+      include WordFilterable
+      include WordFiltersValidatable
+
+      # Override attr_reader word_filter found in WordFilterable
+      # so that we don't raise nil errors when using word_filters.
+      def word_filters
+        @word_filters ||= []
+      end
+
+      def clear_filters
+        self.word_filters = []
+      end
+
+      # Appends word filters to the #word_filters Array.
+      #
+      # If Argument word_filter is nil, a block must be passed to populate
+      # the word_filters with an Array of valid word filter objects.
+      #
+      # This method is used for adding/appending word filters to the
+      # word_filters Array. To replace word filters, use #replace_filters;
+      # to perform any other manipulation of the word_filters Array,
+      # use #word_filters directly.
+      def add_filters(word_filters: nil)
+        return if word_filters.is_a?(Array) && word_filters.blank?
+
+        raise 'A block is required if argument word_filters is nil' if word_filters.nil? && !block_given?
+
+        word_filters ||= []
+        yield word_filters if block_given?
+
+        validate_word_filters word_filters: word_filters
+
+        self.word_filters.concat word_filters
+      end
+      alias append_filters add_filters
+
+      def replace_filters(word_filters:)
+        clear_filters
+        add_filters word_filters: word_filters
+      end
+
+      def filters_on=(on)
+        raise ArgumentError, "Argument on is not true or false: #{on.class}" unless [true, false].include?(on)
+
+        word_filters.each { |word_filter| word_filter.filter_on = on }
+      end
+
+      def filters_matched(word)
+        raise ArgumentError, "Argument word is not a String: #{word.class}" unless word.is_a? String
+
+        return [] if word_filters.blank?
+        return [] if word.empty?
+
+        word_filters.filter_map do |word_filter|
+          word_filter.to_sym if word_filter.filter_match?(word)
+        end
+      end
+
+      def filter_match?(word)
+        filters_matched(word).present?
+      end
+    end
+  end
+end

data/lib/LittleWeasel/filters/word_filter_validatable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Filters
+    # This module validates word filter types.
+    module WordFilterValidatable
+      def self.validate(word_filter:)
+        raise ArgumentError, "Argument word_filter does not quack right: #{word_filter.class}" \
+          unless valid_word_filter?(word_filter: word_filter)
+      end
+
+      # You can use your own word filter 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
+      # filter objects (e.g. Filters::EnUs::NumericFilter) and inherit from
+      # Filters::WordFilter.
+      def self.valid_word_filter?(word_filter:)
+        word_filter.respond_to?(:filter_on?) &&
+          word_filter.respond_to?(:filter_off?) &&
+          word_filter.respond_to?(:filter_on) &&
+          word_filter.respond_to?(:filter_on=) &&
+          word_filter.respond_to?(:filter_match?) &&
+          word_filter.class.respond_to?(:filter_match?)
+      end
+
+      def validate_word_filter(word_filter:)
+        WordFilterValidatable.validate word_filter: word_filter
+      end
+    end
+  end
+end

data/lib/LittleWeasel/filters/word_filterable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'word_filters_validatable'
+
+module LittleWeasel
+  module Filters
+    # This module provides the word_filters attribute for objects that support
+    # word filters.
+    module WordFilterable
+      @word_filters = []
+
+      attr_reader :word_filters
+
+      private
+
+      attr_writer :word_filters
+    end
+  end
+end

data/lib/LittleWeasel/filters/word_filters_validatable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'word_filter_validatable'
+
+module LittleWeasel
+  module Filters
+    # This module provides methods to validate an Array of word filters.
+    module WordFiltersValidatable
+      extend WordFilterValidatable
+
+      def self.validate(word_filters:)
+        return if word_filters.blank?
+
+        unless word_filters.is_a? Array
+          raise ArgumentError,
+            "Argument word_filters is not an Array: #{word_filters.class}"
+        end
+
+        word_filters.each do |word_filter|
+          validate_word_filter word_filter: word_filter
+        end
+      end
+
+      def validate_word_filters(word_filters:)
+        WordFiltersValidatable.validate word_filters: word_filters
+      end
+    end
+  end
+end

data/lib/LittleWeasel/metadata/dictionary_metadata.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+require 'observer'
+require_relative '../modules/class_name_to_symbol'
+require_relative '../modules/configurable'
+require_relative '../modules/dictionary_cache_keys'
+require_relative '../modules/dictionary_cache_servicable'
+require_relative '../modules/dictionary_metadata_servicable'
+require_relative 'metadata_observable_validatable'
+require_relative 'metadatable'
+
+module LittleWeasel
+  module Metadata
+    # This class manages metadata objects related to dictionaries. Metadata
+    # objects defined in LittleWeasel::Configuration#metadata_observers are
+    # added as observers, provided they are in a state to observe
+    # (see Metadata::Metadatable, Metadata::InvalidWords::InvalidWordsMetadata,
+    # etc.).
+    class DictionaryMetadata
+      include Observable
+      include Metadata::Metadatable
+      include Metadata::MetadataObservableValidatable
+      include Modules::ClassNameToSymbol
+      include Modules::Configurable
+      include Modules::DictionaryCacheKeys
+      include Modules::DictionaryCacheServicable
+      include Modules::DictionaryMetadataServicable
+
+      delegate :[], to: :observers
+
+      attr_reader :dictionary_words, :observers
+
+      def initialize(dictionary_words:, dictionary_key:, dictionary_cache:, dictionary_metadata:)
+        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_words.is_a? Hash
+          raise ArgumentError,
+            "Argument dictionary_words is not a Hash: #{dictionary_words.class.name}."
+        end
+
+        self.dictionary_words = dictionary_words
+        self.observers = {}
+
+        refresh
+      end
+
+      def init(_params: nil)
+        dictionary_metadata_service.init(metadata_key: metadata_key)
+        self.metadata = {}
+        notify action: :init
+        refresh_local_metadata
+        self
+      end
+
+      def refresh(_params: nil)
+        refresh_local_metadata
+        if metadata.present?
+          # If there is metadata in the dictionary cache, notify the observers
+          # to use it...
+          notify action: :refresh
+        else
+          # ...otherwise, notify the observers to initialize themselves.
+          init
+        end
+      end
+
+      def notify(action:, params: nil)
+        if count_observers.positive?
+          changed
+          notify_observers action, params
+        end
+        self
+      end
+
+      def add_observers(force: false)
+        delete_observers if force
+
+        raise 'Observers have already been added; use #add_observers(force: true) instead' if count_observers.positive?
+
+        observer_classes = config.metadata_observers
+        yield observer_classes if block_given?
+
+        observer_classes.each do |o|
+          # If the medatata observer is not in a state to observe,
+          # or is turned "off", skip it...
+          #
+          # See Metadata::MetadataObserverable.observe? comments.
+          next unless o.observe?
+
+          # If this observer has already beed added, don't add it again.
+          next if observers.key? o.metadata_key
+
+          observer = o.new(dictionary_metadata_object: self,
+            dictionary_words: dictionary_words,
+            dictionary_key: dictionary_key,
+            dictionary_cache: dictionary_cache,
+            dictionary_metadata: dictionary_metadata)
+
+          # Only add metadata objects that are capable of observing
+          # (i.e. #observe?).
+          add_observer observer if observer.observe?
+        end
+        # This is how each metadata object gets initialized. Only notify if
+        # there are any observers.
+        notify(action: :init) if count_observers.positive?
+        self
+      end
+
+      def add_observer(observer, func = :update)
+        validate_metadata_observable observer
+
+        super
+        observers[observer.metadata_key] = observer
+      end
+
+      def delete_observer(observer)
+        validate_metadata_observable observer
+
+        super
+        observers.delete(observer.metadata_key)
+      end
+
+      def delete_observers
+        super
+        self.observers = {}
+      end
+
+      private
+
+      attr_writer :dictionary_words, :observers
+
+      def update_dictionary_metadata(value:)
+        dictionary_metadata_service.set_dictionary_metadata(value: value, metadata_key: metadata_key)
+      end
+    end
+  end
+end