picky 4.0.0pre6 → 4.0.0

data/lib/picky/api/category/partial.rb

@@ -0,0 +1,26 @@
+module Picky
+  module API
+    module Category
+
+      module Partial
+
+        def extract_partial thing
+          return Generators::Partial::Default unless thing
+
+          if thing.respond_to? :each_partial
+            thing
+          else
+            raise <<-ERROR
+partial options for #{index_name}:#{name} should be either
+* for example a Partial::Substring.new(from: m, to: n), Partial::Postfix.new(from: n), Partial::Infix.new(min: m, max: n) etc.
+or
+* an object that responds to #each_partial(str_or_sym) and yields each partial
+ERROR
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/picky/api/category/similarity.rb

@@ -0,0 +1,26 @@
+module Picky
+  module API
+    module Category
+
+      module Similarity
+
+        def extract_similarity thing
+          return Generators::Similarity::Default unless thing
+
+          if thing.respond_to?(:encode) && thing.respond_to?(:prioritize)
+            thing
+          else
+            raise <<-ERROR
+similarity options for #{index_name}:#{name} should be either
+* for example a Similarity::Phonetic.new(n), Similarity::Metaphone.new(n), Similarity::DoubleMetaphone.new(n) etc.
+or
+* an object that responds to #encode(text) => encoded_text and #prioritize(array_of_encoded, encoded)
+ERROR
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/picky/api/category/weight.rb

@@ -0,0 +1,26 @@
+module Picky
+  module API
+    module Category
+
+      module Weight
+
+        def extract_weight thing
+          return Generators::Weights::Default unless thing
+
+          if thing.respond_to? :weight_for
+            thing
+          else
+            raise <<-ERROR
+weight options for #{index_name}:#{name} should be either
+* for example a Weights::Logarithmic.new, Weights::Constant.new(int = 0), Weights::Dynamic.new(&block) etc.
+or
+* an object that responds to #weight_for(amount_of_ids_for_token) => float
+ERROR
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/picky/api/search/boost.rb

@@ -0,0 +1,28 @@
+module Picky
+  module API
+    module Search
+
+      module Boost
+
+        def extract_boosts thing
+          if thing.respond_to?(:boost_for)
+            thing
+          else
+            if thing.respond_to?(:[])
+              Query::Boosts.new thing
+            else
+              raise <<-ERROR
+boost options for a Search should be either
+* for example a Hash { [:name, :surname] => +3 }
+or
+* an object that responds to #boost_for(combinations) and returns a boost float
+ERROR
+            end
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/picky/api/source.rb

@@ -0,0 +1,35 @@
+module Picky
+  module API
+    module Source
+
+      def extract_source thing, options = {}
+        if thing.respond_to?(:each) || thing.respond_to?(:call)
+          thing
+        else
+          return if options[:nil_ok]
+          if respond_to? :name
+            if @index
+              location = " #{@index.name}:#{name}"
+            else
+              location = " #{name}"
+            end
+          else
+            location = ''
+          end
+          raise ArgumentError.new(<<-ERROR)
+The#{location} source should respond to either the method #each or
+it can be a lambda/block, returning such a source.
+ERROR
+        end
+      end
+
+      # Get the actual source if it is wrapped in a time
+      # capsule, i.e. a block/lambda.
+      #
+      def unblock_source
+        @source.respond_to?(:call) ? @source.call : @source
+      end
+
+    end
+  end
+end

data/lib/picky/api/tokenizer/character_substituter.rb

@@ -0,0 +1,22 @@
+module Picky
+  module API
+    module Tokenizer
+
+      module CharacterSubstituter
+
+        def extract_character_substituter thing
+          if thing.respond_to? :substitute
+            thing
+          else
+            raise ArgumentError.new <<-ERROR
+The substitutes_characters_with option needs a character substituter,
+which responds to #substitute(text) and returns substituted_text."
+ERROR
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/picky/api/tokenizer.rb

@@ -0,0 +1,37 @@
+module Picky
+  module API
+
+    module Tokenizer
+
+      def extract_tokenizer thing
+        return unless thing
+        if thing.respond_to? :tokenize
+          thing
+        else
+          if thing.respond_to? :[]
+            Picky::Tokenizer.new thing
+          else
+            if respond_to? :name
+              location = ' for '
+              if @index
+                location += "#{@index.name}:#{name}"
+              else
+                location += "#{name}"
+              end
+            else
+              location = ''
+            end
+            raise <<-ERROR
+indexing options#{location} should be either
+* a Hash
+or
+* an object that responds to #tokenize(text) => [[token1, ...], [original1, ...]]
+ERROR
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/picky/bundle.rb

@@ -126,7 +126,7 @@ module Picky
     # Note: Does not return itself.
     #
     def similar text
-      code = similarity_strategy.encoded text
+      code = similarity_strategy.encode text
       return [] unless code
       similar_codes = @similarity[code]
       if similar_codes.blank?

data/lib/picky/bundle_realtime.rb

@@ -22,7 +22,7 @@ module Picky
           # Since no element uses this sym anymore, we can delete the similarity for it.
           # TODO Not really. Since multiple syms can point to the same encoded.
           #
-          @similarity.delete self.similarity_strategy.encoded(str_or_sym)
+          @similarity.delete self.similarity_strategy.encode(str_or_sym)
         else
           @weights[str_or_sym] = self.weight_strategy.weight_for ids.size
         end
@@ -67,7 +67,7 @@ module Picky
     # Add string/symbol to similarity index.
     #
     def add_similarity str_or_sym, where = :unshift
-      if encoded = self.similarity_strategy.encoded(str_or_sym)
+      if encoded = self.similarity_strategy.encode(str_or_sym)
         similars = @similarity[encoded] ||= []
 
         # Not completely correct, as others will also be affected, but meh.

data/lib/picky/category.rb

@@ -2,6 +2,12 @@ module Picky
 
   class Category
 
+    include API::Tokenizer
+    include API::Source
+    include API::Category::Weight
+    include API::Category::Partial
+    include API::Category::Similarity
+
     attr_accessor :exact,
                   :partial
     attr_reader :name,
@@ -33,9 +39,9 @@ module Picky
 
       # Indexing.
       #
-      @source     = options[:source]
-      @from       = options[:from]
-      @tokenizer  = options[:tokenizer]
+      @source    = extract_source options[:source], nil_ok: true
+      @from      = options[:from]
+      @tokenizer = extract_tokenizer options[:indexing]
 
       @key_format = options.delete :key_format
       @backend    = options.delete :backend
@@ -44,9 +50,9 @@ module Picky
 
       # @symbols    = options[:use_symbols] || index.use_symbols? # TODO Symbols.
 
-      weights    = options[:weight]     || Generators::Weights::Default
-      partial    = options[:partial]    || Generators::Partial::Default
-      similarity = options[:similarity] || Generators::Similarity::Default
+      weights    = extract_weight options[:weight]
+      partial    = extract_partial options[:partial]
+      similarity = extract_similarity options[:similarity]
 
       no_partial    = Generators::Partial::None.new
       no_similarity = Generators::Similarity::None.new

data/lib/picky/category_indexing.rb

@@ -78,13 +78,7 @@ module Picky
     # If we have no explicit source, we'll check the index for one.
     #
     def source
-      extract_source || @index.source
-    end
-    # Extract the actual source if it is wrapped in a time
-    # capsule, i.e. a block/lambda.
-    #
-    def extract_source
-      @source = @source.respond_to?(:call) ? @source.call : @source
+      (@source = extract_source(@source, nil_ok: true)) || @index.source
     end
 
     # Return the key format.
@@ -96,7 +90,7 @@ module Picky
     # Default is to_i.
     #
     def key_format
-      @key_format ||= source.respond_to?(:key_format) && source.key_format || @index.key_format || :to_i
+      @key_format ||= @index.key_format || :to_i
     end
 
     # Where the data is taken from.

data/lib/picky/generators/similarity/double_metaphone.rb

@@ -18,7 +18,7 @@ module Picky
         #
         # Returns a symbol.
         #
-        def encoded str_or_sym
+        def encode str_or_sym
           str_or_sym.double_metaphone
         end
 

data/lib/picky/generators/similarity/metaphone.rb

@@ -18,7 +18,7 @@ module Picky
         #
         # Returns a symbol.
         #
-        def encoded str_or_sym
+        def encode str_or_sym
           str_or_sym.metaphone
         end
 

data/lib/picky/generators/similarity/none.rb

@@ -10,7 +10,7 @@ module Picky
 
         # Does not encode text. Just returns nil.
         #
-        def encoded text
+        def encode text
           nil
         end
 

data/lib/picky/generators/similarity/soundex.rb

@@ -18,7 +18,7 @@ module Picky
         #
         # Returns a symbol.
         #
-        def encoded str_or_sym
+        def encode str_or_sym
           str_or_sym.soundex
         end
 

data/lib/picky/index_indexing.rb

@@ -4,6 +4,9 @@ module Picky
   #
   class Index
 
+    include API::Tokenizer
+    include API::Source
+
     include Helpers::Indexing
 
     # Delegators for indexing.
@@ -17,11 +20,7 @@ module Picky
     # Parameters are the exact same as for indexing.
     #
     def indexing options = {}
-      @tokenizer = if options.respond_to?(:tokenize)
-        options
-      else
-        options && Tokenizer.new(options)
-      end
+      @tokenizer = extract_tokenizer options
     end
 
     #
@@ -99,26 +98,7 @@ module Picky
     #
     def source some_source = nil, &block
       some_source ||= block
-      some_source ? (check_source(some_source); @source = some_source) : (@source && extract_source)
-    end
-    # Extract the actual source if it is wrapped in a time
-    # capsule, i.e. a block/lambda.
-    #
-    def extract_source
-      @source.respond_to?(:call) ? @source.call : @source
-    end
-    def check_source source # :nodoc:
-      raise ArgumentError.new(<<-SOURCE
-
-
-The index "#{name}" should use a data source that responds to either the method #each, or the method #harvest, which yields(id, text), OR it can be a lambda/block, returning such a source.
-Or it could use one of the built-in sources:
-  Sources::#{(Sources.constants - [:Base, :Wrappers, :NoCSVFileGiven, :NoCouchDBGiven]).join(',
-  Sources::')}
-
-
-SOURCE
-) unless source.respond_to?(:each) || source.respond_to?(:harvest) || source.respond_to?(:call)
+      some_source ? (@source = extract_source(some_source)) : unblock_source
     end
 
     # Define a key_format on the index.

data/lib/picky/loader.rb

@@ -165,10 +165,6 @@ module Picky
         load_relative 'query/token'
         load_relative 'query/tokens'
 
-        # Tokenizer.
-        #
-        load_relative 'tokenizer'
-
         # Query combinations, qualifiers, weigher.
         #
         load_relative 'query/combination'
@@ -179,7 +175,7 @@ module Picky
 
         load_relative 'query/qualifier_category_mapper'
 
-        load_relative 'query/weights'
+        load_relative 'query/boosts'
 
         load_relative 'query/indexes'
         load_relative 'query/indexes_check'
@@ -187,6 +183,20 @@ module Picky
       # Loads the user interface parts.
       #
       def load_user_interface
+        # Load API parts.
+        #
+        load_relative 'api/tokenizer'
+        load_relative 'api/tokenizer/character_substituter'
+        load_relative 'api/source'
+        load_relative 'api/category/weight'
+        load_relative 'api/category/partial'
+        load_relative 'api/category/similarity'
+        load_relative 'api/search/boost'
+
+        # Tokenizer.
+        #
+        load_relative 'tokenizer'
+
         # Load harakiri.
         #
         load_relative 'rack/harakiri'

data/lib/picky/query/allocation.rb

@@ -40,7 +40,7 @@ module Picky
           0
         else
           @backend.weight(@combinations) +
-            @combinations.weighted_score(weights)
+            @combinations.boost_for(weights)
         end
       end
 

data/lib/picky/query/{weights.rb → boosts.rb}

@@ -2,7 +2,7 @@ module Picky
 
   module Query
 
-    # Calculates scores/weights for combinations.
+    # Calculates boosts for combinations.
     #
     # Example:
     #   Someone searches for peter fish.
@@ -11,34 +11,34 @@ module Picky
     #   and
     #     [:name, :surname]
     #
-    # This class is concerned with calculating scores
+    # This class is concerned with calculating boosts
     # for the category combinations.
     #
     # Implement either
-    #   #score_for(combinations)
+    #   #boost_for(combinations)
     # or
-    #   #weight_for(category_names) # Subclass this class for this.
+    #   #boost_for_categories(category_names) # Subclass this class for this.
     #
-    # And return a weight.
+    # And return a boost (float).
     #
-    class Weights
+    class Boosts
 
-      attr_reader :weights
+      attr_reader :boosts
 
       delegate :empty?,
-               :to => :weights
+               :to => :boosts
 
       # Needs a Hash of
       #   [:category_name1, :category_name2] => +3
       # (some positive or negative weight)
       #
-      def initialize weights = {}
-        @weights = weights
+      def initialize boosts = {}
+        @boosts = boosts
       end
 
       # API.
       #
-      # Get the weight for an array of category names.
+      # Get the boost for an array of category names.
       #
       # Example:
       #   [:name, :height, :color] returns +3, but
@@ -47,8 +47,8 @@ module Picky
       # Note: Use Array#clustered_uniq_fast to make
       #       [:a, :a, :b, :a] => [:a, :b, :a]
       #
-      def weight_for category_names
-        @weights[category_names.clustered_uniq_fast] || 0
+      def boost_for_categories names
+        @boosts[names.clustered_uniq_fast] || 0
       end
 
       # API.
@@ -60,22 +60,22 @@ module Picky
       # Note: Cache this if more complicated weighings become necessary.
       # Note: Maybe make combinations comparable to Symbols?
       #
-      def score_for combinations
-        weight_for combinations.map(&:category_name)
+      def boost_for combinations
+        boost_for_categories combinations.map(&:category_name)
       end
 
       # A Weights instance is == to another if
       # the weights are the same.
       #
       def == other
-        @weights == other.weights
+        @boosts == other.boosts
       end
 
       # Prints out a nice representation of the
       # configured weights.
       #
       def to_s
-        "#{self.class}(#{@weights})"
+        "#{self.class}(#{@boosts})"
       end
 
     end

data/lib/picky/query/combinations.rb

@@ -28,8 +28,8 @@ module Picky
       def score
         @combinations.sum &:weight
       end
-      def weighted_score weights
-        weights.score_for @combinations
+      def boost_for weights
+        weights.boost_for @combinations
       end
 
       # Filters the tokens and categories such that categories

data/lib/picky/search.rb

@@ -15,11 +15,13 @@ module Picky
   #
   class Search
 
+    include API::Search::Boost
+
     include Helpers::Measuring
 
     attr_reader   :indexes
     attr_accessor :tokenizer,
-                  :weights
+                  :boosts
 
     delegate :ignore,
              :to => :indexes
@@ -27,11 +29,11 @@ module Picky
     # Takes:
     # * A number of indexes
     #
-    # It is also possible to define the tokenizer and weights like so.
+    # It is also possible to define the tokenizer and boosts like so.
     # Example:
     #   search = Search.new(index1, index2, index3) do
     #     searching removes_characters: /[^a-z]/ # etc.
-    #     weights [:author, :title] => +3,
+    #     boosts [:author, :title] => +3,
     #             [:title, :isbn] => +1
     #   end
     #
@@ -41,7 +43,7 @@ module Picky
       instance_eval(&Proc.new) if block_given?
 
       @tokenizer ||= Tokenizer.searching # THINK Not dynamic. Ok?
-      @weights   ||= Query::Weights.new
+      @boosts    ||= Query::Boosts.new
       @ignore_unassigned = false if @ignore_unassigned.nil?
 
       self
@@ -87,7 +89,7 @@ module Picky
     # Note: When using the Picky interface, do not terminate too
     # early as this will kill off the allocation selections.
     # A value of
-    #    early_terminate 5
+    #    terminate_early 5
     # is probably a good idea to show the user 5 extra
     # beyond the needed ones.
     #
@@ -117,29 +119,25 @@ module Picky
     #
     # or
     #
-    #   # Explicitly add a random number (0...1) to the weights.
+    #   # Explicitly add a random number (0...1) to the boosts.
     #   #
-    #   my_weights = Class.new do
+    #   my_boosts = Class.new do
     #     # Instance only needs to implement
-    #     #   score_for combinations
+    #     #   boost_for combinations
     #     # and return a number that is
-    #     # added to the weight.
+    #     # added to the score.
     #     #
-    #     def score_for combinations
+    #     def boost_for combinations
     #       rand
     #     end
     #   end.new
     #
     #   search = Search.new(books_index, dvd_index, mp3_index) do
-    #     boost my_weights
+    #     boost my_boosts
     #   end
     #
-    def boost weights
-      @weights = if weights.respond_to?(:score_for)
-        weights
-      else
-        Query::Weights.new weights
-      end
+    def boost boosts
+      @boosts = extract_boosts boosts
     end
 
     # Ignore the given token if it cannot be matched to a category.
@@ -225,7 +223,7 @@ module Picky
     # Gets sorted allocations for the tokens.
     #
     def sorted_allocations tokens, amount = nil # :nodoc:
-      indexes.prepared_allocations_for tokens, weights, amount
+      indexes.prepared_allocations_for tokens, boosts, amount
     end
 
     # Display some nice information for the user.
@@ -234,7 +232,7 @@ module Picky
       s = "#{self.class}("
       ary = []
       ary << @indexes.indexes.map(&:name).join(', ') unless @indexes.indexes.empty?
-      ary << "weights: #{@weights}" if @weights
+      ary << "boosts: #{@boosts}" if @boosts
       s << ary.join(', ')
       s << ")"
       s

data/lib/picky/tokenizer.rb

@@ -6,15 +6,19 @@ module Picky
   #
   class Tokenizer
 
+    extend API::Tokenizer
+
+    include API::Tokenizer::CharacterSubstituter
+
     def self.default_indexing_with options = {}
-      @indexing = options.respond_to?(:tokenize) ? options : new(options)
+      @indexing = extract_tokenizer options
     end
     def self.indexing
       @indexing ||= new
     end
 
     def self.default_searching_with options = {}
-      @searching = options.respond_to?(:tokenize) ? options : new(options)
+      @searching = extract_tokenizer options
     end
     def self.searching
       @searching ||= new
@@ -108,8 +112,7 @@ Case sensitive?     #{@case_sensitive ? "Yes." : "-"}
     # Default is European Character substitution.
     #
     def substitutes_characters_with substituter = CharacterSubstituters::WestEuropean.new
-      raise ArgumentError.new "The substitutes_characters_with option needs a character substituter, which responds to #substitute." unless substituter.respond_to?(:substitute)
-      @substituter = substituter
+      @substituter = extract_character_substituter substituter
     end
     def substitute_characters text
       substituter?? substituter.substitute(text) : text