LittleWeasel 3.0.4 → 4.0.0

data/lib/LittleWeasel/block_results.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+require_relative 'word_results'
+
+module LittleWeasel
+  # This class represents the results of gathering information about a word
+  # block (group of words).
+  class BlockResults
+    # :reek:Attribute - Ignored, it doesn't make sense to create a formal setter method.
+    attr_reader :original_word_block, :word_results
+
+    def initialize(original_word_block:)
+      self.original_word_block = original_word_block
+      self.word_results = []
+    end
+
+    def <<(word_result)
+      unless word_result.is_a? WordResults
+        raise ArgumentError, "Argument word_result is not a WordResults object: #{word_result.class}"
+      end
+
+      word_results << word_result
+    end
+
+    # Calls #success? on all WordResults objects. Returns true if all
+    # WordResults return true; false is returned otherwise.
+    def success?
+      return false unless word_results.present?
+
+      word_results.all?(&:success?)
+    end
+
+    # Returns true if all WordResults object words are valid (#word_valid?);
+    # false otherwise.
+    def words_valid?
+      return false unless word_results.present?
+
+      word_results.all?(&:word_valid?)
+    end
+
+    # Returns true if all WordResults object words have filter matches (#filters_match?);
+    # false otherwise.
+    def filters_match?
+      return false unless word_results.present?
+
+      word_results.all?(&:filter_match?)
+    end
+
+    # Returns true if all WordResults object words have been preprocessed (#preprocessed_words?);
+    # false otherwise.
+    def preprocessed_words?
+      return false unless word_results.present?
+
+      word_results.all?(&:preprocessed_word?)
+    end
+
+    # Returns an Array of the results of calling
+    # #preprocessed_word_or_original_word on all WordResults objects.
+
+    # Calls #preprocessed_word_or_original_word on all WordResults objects.
+    # An Array of the results is returned.
+    def preprocessed_words_or_original_words
+      return [] unless word_results.present?
+
+      word_results.map(&:preprocessed_word_or_original_word)
+    end
+
+    # Returns true if all WordResults object words have been cached (#words_cached?);
+    # false otherwise.
+    def words_cached?
+      return false unless word_results.present?
+
+      word_results.all?(&:word_cached?)
+    end
+
+    private
+
+    attr_writer :original_word_block, :word_results
+  end
+end

data/lib/LittleWeasel/configure.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# This is the configuration for LittleWeasel.
+module LittleWeasel
+  class << self
+    attr_reader :configuration
+
+    # Returns the application configuration object.
+    #
+    # @return [Configuration] the application Configuration object.
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    private
+
+    attr_writer :configuration
+  end
+
+  # This class encapsulates the configuration properties for this gem and
+  # provides methods and attributes that allow for management of the same.
+  #
+  # attr_reader :max_dictionary_file_megabytes, :max_invalid_words_bytesize, :metadata_observers
+  class Configuration
+    attr_reader :max_dictionary_file_megabytes,
+      :max_invalid_words_bytesize, :metadata_observers, :word_block_regex
+
+    # The constructor; calls {#reset}.
+    def initialize
+      reset
+    end
+
+    # Resets the configuration settings to their default values.
+    #
+    # @return [void]
+    def reset
+      @max_dictionary_file_megabytes = 5
+      @max_invalid_words_bytesize = 25_000
+      @metadata_observers = [
+        LittleWeasel::Metadata::InvalidWordsMetadata
+      ]
+      # TODO: Is this the correct regex to use, or is there something better?
+      # @word_block_regex = /\s+(?=(?:[^"]*"[^"]*")*[^"]*$)/
+      # @word_block_regex = /(?:(?:[\-A-Za-z0-9]|\d(?!\d|\b))+(?:'[\-A-Za-z0-9]+)?)/
+      # @word_block_regex = /(?:(?:[\-a-z0-9]|\d(?!\d|\b))+(?:'[\-a-z0-9]+)?)/i
+      @word_block_regex = /[[[:word:]]'-]+/
+    end
+
+    # Returns the maximum consumable dictionary size in bytes. Dictionaries
+    # larger than {#max_dictionary_file_bytes} will raise an error.
+    #
+    # The default is 5 megabytes.
+    #
+    # @return [Integer] the maximum number of bytes for a dictionary.
+    def max_dictionary_file_bytes
+      @max_dictionary_file_megabytes * 1_000_000
+    end
+
+    # If {#max_invalid_words_bytesize} is > 0, true will be returned; false
+    # otherwise.
+    #
+    # @return [true, false] based on {#max_invalid_words_bytesize}.
+    def max_invalid_words_bytesize?
+      max_invalid_words_bytesize.positive?
+    end
+
+    # rubocop: disable Style/TrivialAccessors
+    def max_dictionary_file_megabytes=(value)
+      @max_dictionary_file_megabytes = value
+    end
+
+    # Sets the maximum cache size (in bytes) for invalid words. If
+    # less than or equal to 0, invalid words will NOT be cached.
+    #
+    # If greater than 0, invalid words will be cached up to and including
+    # {#max_invalid_words_bytesize} bytes.
+    #
+    # @see #max_invalid_words_bytesize?
+    def max_invalid_words_bytesize=(value)
+      value = 0 if value.negative?
+      @max_invalid_words_bytesize = value
+    end
+
+    def metadata_observers=(value)
+      raise ArgumentError, "Argument value is not an Array: #{value.class}" unless value.is_a? Array
+
+      # TODO: Limit the amount of observer classes, exploits?
+
+      @metadata_observers = value
+    end
+
+    def word_block_regex=(value)
+      @word_block_regex = value
+    end
+    # rubocop: enable Style/TrivialAccessors
+  end
+end

data/lib/LittleWeasel/dictionary.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative 'block_results'
+require_relative 'filters/word_filter_managable'
+require_relative 'metadata/dictionary_metadata'
+require_relative 'modules/configurable'
+require_relative 'modules/dictionary_cache_servicable'
+require_relative 'modules/dictionary_keyable'
+require_relative 'modules/dictionary_metadata_servicable'
+require_relative 'preprocessors/word_preprocessor_managable'
+require_relative 'word_results'
+
+module LittleWeasel
+  class Dictionary
+    include Filters::WordFilterManagable
+    include Modules::Configurable
+    include Modules::DictionaryCacheServicable
+    include Modules::DictionaryKeyable
+    include Modules::DictionaryMetadataServicable
+    include Preprocessors::WordPreprocessorManagable
+
+    attr_reader :dictionary_metadata_object, :dictionary_words
+
+    def initialize(dictionary_key:, dictionary_words:, 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
+
+      unless dictionary_words.is_a?(Array)
+        raise ArgumentError,
+          "Argument dictionary_words is not an Array: #{dictionary_words.class}"
+      end
+
+      # Set up the dictionary metadata object and observers
+      self.dictionary_words = self.class.to_hash(dictionary_words: dictionary_words)
+      self.dictionary_metadata_object = create_dictionary_metadata
+      dictionary_metadata_object.add_observers
+
+      add_filters word_filters: word_filters || []
+      add_preprocessors word_preprocessors: word_preprocessors || []
+    end
+
+    class << self
+      def to_hash(dictionary_words:)
+        dictionary_words.each_with_object(Hash.new(false)) { |word, hash| hash[word] = true; }
+      end
+    end
+
+    def word_results(word)
+      # TODO: Make max word size configurable.
+      raise ArgumentError, "Argument word is not a String: #{word.class}" unless word.is_a?(String)
+
+      preprocessed_words = preprocess(word: word)
+      preprocessed_word = preprocessed_words.preprocessed_word
+      filters_matched = filters_matched(preprocessed_word || word)
+      word_results = WordResults.new(original_word: word,
+        filters_matched: filters_matched,
+        preprocessed_words: preprocessed_words,
+        word_cached: dictionary_words.include?(preprocessed_word || word),
+        word_valid: dictionary_words[preprocessed_word || word] || false)
+
+      dictionary_metadata_object.notify(action: :word_search,
+        params: { word_results: word_results })
+
+      word_results
+    end
+
+    def block_results(word_block)
+      # TODO: Make max word_block size configurable.
+      raise ArgumentError, "Argument word_block is not a String: #{word_block.class}" unless word_block.is_a?(String)
+      raise ArgumentError, "Argument word_block is empty: #{word_block.class}" unless word_block.present?
+
+      BlockResults.new(original_word_block: word_block).tap do |block_results|
+        word_block.scan(config.word_block_regex)&.map do |word|
+          block_results << word_results(word)
+        end
+      end
+    end
+
+    # This method returns true if this dictionary object is detached from the
+    # dictionary cache; this can happen if the dictionary object is unloaded
+    # from the dictionary cache(DictionaryManager#unload_dictionary) or the
+    # dictionary is killed (DictionaryManager#kill_dictionary).
+    def detached?
+      !dictionary_cache_service.dictionary_object?
+    end
+
+    # This method returns a count of VALID words in the dictionary.
+    def count
+      dictionary_words.each_pair.count { |_word, valid| valid }
+    end
+
+    # This method returns a count of all VALID and INVALID words in
+    # the dictionary.
+    def count_all_words
+      dictionary_words.count
+    end
+
+    # This method returns a count of all INVALID words in the dictionary.
+    def count_invalid_words
+      dictionary_words.each_pair.count { |_word, valid| !valid }
+    end
+
+    private
+
+    attr_writer :dictionary_metadata_object, :dictionary_words
+
+    def create_dictionary_metadata
+      # We unconditionally attach metadata to this dictionary. DictionaryMetadata
+      # only attaches the metadata services that are turned "on".
+      Metadata::DictionaryMetadata.new(
+        dictionary_words: dictionary_words,
+        dictionary_key: dictionary_key,
+        dictionary_cache: dictionary_cache,
+        dictionary_metadata: dictionary_metadata
+      )
+    end
+  end
+end

data/lib/LittleWeasel/dictionary_key.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'modules/language_validatable'
+require_relative 'modules/locale'
+require_relative 'modules/region_validatable'
+require_relative 'modules/taggable'
+
+module LittleWeasel
+  # This class describes a unique key associated with a particular dictionary
+  # file. Dictionary keys are used to identify a dictionary on which an action
+  # should be performed.
+  class DictionaryKey
+    include Modules::LanguageValidatable
+    include Modules::Locale
+    include Modules::RegionValidatable
+    include Modules::Taggable
+
+    attr_reader :language, :region
+
+    def initialize(language:, region: nil, tag: nil)
+      validate_language language: language
+      self.language = self.class.normalize_language language
+
+      validate_region region: region
+      self.region = self.class.normalize_region region
+
+      validate_tag tag: tag
+      self.tag = tag
+    end
+
+    def key
+      return locale unless tagged?
+
+      "#{locale}-#{tag}"
+    end
+    alias to_s key
+
+    class << self
+      def key(language:, region: nil, tag: nil)
+        new(language: language, region: region, tag: tag).key
+      end
+    end
+
+    private
+
+    attr_writer :language, :region
+  end
+end

data/lib/LittleWeasel/dictionary_manager.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+require_relative 'dictionary_key'
+require_relative 'modules/dictionary_key_validatable'
+
+module LittleWeasel
+  # This class provides dictionary management functionality.
+  class DictionaryManager
+    include Modules::DictionaryKeyValidatable
+
+    attr_reader :dictionary_cache, :dictionary_metadata
+
+    def initialize
+      self.dictionary_cache = {}
+      self.dictionary_metadata = {}
+      init
+    end
+
+    def dictionary_for(dictionary_key:)
+      validate_dictionary_key dictionary_key: dictionary_key
+
+      unless dictionary_cache_service(dictionary_key: dictionary_key).dictionary_exists?
+        # TODO: Raise an error or let the service handle it?
+      end
+
+      dictionary_cache_service(dictionary_key: dictionary_key).dictionary_object!
+    end
+
+    # Adds a dictionary file source, creates the dictionary and returns the
+    # Dictionary object.
+    def create_dictionary_from_file(dictionary_key:, file:, word_filters: nil, word_preprocessors: nil)
+      validate_dictionary_key dictionary_key: dictionary_key
+
+      dictionary_creator_service(dictionary_key: dictionary_key, word_filters: word_filters,
+        word_preprocessors: word_preprocessors).from_file_source file: file
+    end
+
+    # Adds a dictionary memory source, creates the dictionary and returns the
+    # Dictionary object.
+    def create_dictionary_from_memory(dictionary_key:, dictionary_words:, word_filters: nil, word_preprocessors: nil)
+      validate_dictionary_key dictionary_key: dictionary_key
+
+      dictionary_creator_service(dictionary_key: dictionary_key, word_filters: word_filters,
+        word_preprocessors: word_preprocessors).from_memory_source dictionary_words: dictionary_words
+    end
+
+    # Removes any and all traces of the dictionary associated with the
+    # dictionary key from the dictionary cache - the Dictionary object, file
+    # reference and any metadata associated with the dictionary are completely
+    # removed from the dictionary cache.
+    def kill_dictionary(dictionary_key:)
+      validate_dictionary_key dictionary_key: dictionary_key
+
+      dictionary_killer_service(dictionary_key: dictionary_key).execute
+      self
+    end
+
+    # Resets the cache and metadata by clearing it out completely.
+    def init
+      Services::DictionaryCacheService.init dictionary_cache: dictionary_cache
+      Services::DictionaryMetadataService.init dictionary_metadata: dictionary_metadata
+      self
+    end
+
+    private
+
+    attr_writer :dictionary_cache, :dictionary_metadata
+
+    def dictionary_cache_service(dictionary_key:)
+      Services::DictionaryCacheService.new dictionary_key: dictionary_key, dictionary_cache: dictionary_cache
+    end
+
+    def dictionary_creator_service(dictionary_key:, word_filters:, word_preprocessors:)
+      Services::DictionaryCreatorService.new dictionary_key: dictionary_key, dictionary_cache: dictionary_cache,
+        dictionary_metadata: dictionary_metadata, word_filters: word_filters,
+        word_preprocessors: word_preprocessors
+    end
+
+    def dictionary_killer_service(dictionary_key:)
+      Services::DictionaryKillerService.new dictionary_key: dictionary_key, dictionary_cache: dictionary_cache,
+        dictionary_metadata: dictionary_metadata
+    end
+  end
+end

data/lib/LittleWeasel/errors/dictionary_file_already_loaded_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LittleWeasel
+  module Errors
+    # This class describes an error when a dictionary is already loaded and
+    # should not be loaded again.
+    class DictionaryFileAlreadyLoadedError < StandardError; end
+  end
+end