picky 1.1.6 → 1.1.7

data/lib/picky/application.rb

@@ -179,7 +179,7 @@ class Application
     # * source: The source the data comes from. See Sources::Base. # TODO Sources (all).
     #
     # Options:
-    # * result_type: # TODO Rename.
+    # * result_identifier: # TODO Rename.
     #
     def index name, source, options = {}
       IndexAPI.new name, source, options

data/lib/picky/index_api.rb

@@ -1,7 +1,7 @@
 # This class defines the indexing and index API that is exposed to the user
 # as the #index method inside the Application class.
 #
-# It provides a single front for both indexing and index options.
+# It provides a single front for both indexing and index options. We suggest to always use the index API.
 #
 # Note: An Index holds both an *Indexed*::*Index* and an *Indexing*::*Type*.
 #
@@ -11,12 +11,13 @@ class IndexAPI
   
   # Create a new index with a given source.
   #
-  # Parameters:
+  # === Parameters
   # * name: A name that will be used for the index directory and in the Picky front end.
   # * source: Where the data comes from, e.g. Sources::CSV.new(...)
   #
-  # Options:
-  # * after_indexing: Currently only used in the db source. Executes the given after_indexing as SQL after the indexing process.
+  # === Options
+  # * result_identifier: Use if you'd like a different identifier/name in the results than the name of the index.
+  # * after_indexing: As of this writing only used in the db source. Executes the given after_indexing as SQL after the indexing process.
   #
   def initialize name, source, options = {}
     @name     = name
@@ -30,10 +31,10 @@ class IndexAPI
   
   # Defines a searchable category on the index.
   #
-  # Parameters:
-  # category_name: This identifier is used in the front end, but also to categorize query text. For example, “title:hobbit” will narrow the hobbit query on categories with the identifier :title.
+  # === Parameters
+  # * category_name: This identifier is used in the front end, but also to categorize query text. For example, “title:hobbit” will narrow the hobbit query on categories with the identifier :title.
   #
-  # Options:
+  # === Options
   # * partial: Partial::None.new or Partial::Substring.new(from: starting_char, to: ending_char). Default is Partial::Substring.new(from: -3, to: -1).
   # * similarity: Similarity::None.new or Similarity::Phonetic.new(similar_words_searched). Default is Similarity::None.new.
   # * qualifiers: An array of qualifiers with which you can define which category you’d like to search, for example “title:hobbit” will search for hobbit in just title categories. Example: qualifiers: [:t, :titre, :title] (use it for example with multiple languages). Default is the name of the category.
@@ -53,9 +54,9 @@ class IndexAPI
   end
   alias category define_category
   
-  #  HIGHLY EXPERIMENTAL
+  #  HIGHLY EXPERIMENTAL Try if you feel "beta" ;)
   #
-  # Make this category range searchable.
+  # Make this category range searchable with a fixed range. If you need other ranges, define another category with a different range value.
   #
   # Example:
   # You have data values inside 1..100, and you want to have Picky return
@@ -63,33 +64,61 @@ class IndexAPI
   # 45, 46, or 47.2, 48.9, in a range of 2 around 47, so (45..49).
   #
   # Then you use:
-  #  my_index.define_location :values_inside_1_100, 2
+  #  my_index.define_ranged_category :values_inside_1_100, 2
   #
   # Optionally, you give it a precision value to reduce the error margin
   # around 47 (Picky is a bit liberal).
-  #  my_index.define_location :values_inside_1_100, 2, precision: 5
+  #  my_index.define_ranged_category :values_inside_1_100, 2, precision: 5
   #
   # This will force Picky to maximally be wrong 5% of the given range value
-  # (5% of 2 = 0.1).
+  # (5% of 2 = 0.1) instead of the default 20% (20% of 2 = 0.4).
   #
-  # We suggest not to use more than 5 as a higher precision is more performance intensive.
+  # We suggest not to use much more than 5 as a higher precision is more performance intensive for less and less precision gain.
   #
-  # Parameters:
-  # * name: The name as used in #define_category.
-  # * radius: The range (in km) around the query point which we search for results.
+  # == Protip 1
+  #
+  # Create two ranged categories to make an area search:
+  #   index.define_ranged_category :x, 1
+  #   index.define_ranged_category :y, 1
+  #
+  # Search for it using for example:
+  #   x:133, y:120
+  #
+  # This will search this square area (* = 133, 120: The "search" point entered):
+  # 
+  #    132       134
+  #     |         |
+  #   --|---------|-- 121
+  #     |         |
+  #     |    *    |
+  #     |         |
+  #   --|---------|-- 119
+  #     |         | 
+  #
+  # Note: The area does not need to be square, but can be rectangular.
+  #
+  # == Protip 2
+  #
+  # Create three ranged categories to make a volume search.
+  #
+  # Or go crazy and use 4 ranged categories for a space/time search! ;)
+  #
+  # === Parameters
+  # * category_name: The category_name as used in #define_category.
+  # * range: The range (in the units of your data values) around the query point where we search for results.
   #
   #  -----|<- range  ->*------------|-----
   #
-  # Options
-  # * precision # Default 1 (20% error margin, very fast), up to 5 (5% error margin, slower) makes sense.
-  # * from: # The data category to take the data for this category from.
+  # === Options
+  # * precision: Default is 1 (20% error margin, very fast), up to 5 (5% error margin, slower) makes sense.
+  # * ... all options of #define_category.
   #
-  def define_location name, range, options = {}
+  def define_ranged_category category_name, range, options = {}
     precision = options[:precision]
     
     options = { partial: Partial::None.new }.merge options
     
-    define_category name, options do |indexing, indexed|
+    define_category category_name, options do |indexing, indexed|
       indexing.source    = Sources::Wrappers::Location.new indexing, grid: range, precision: precision
       indexing.tokenizer = Tokenizers::Index.new
       
@@ -98,11 +127,11 @@ class IndexAPI
       indexed.partial = exact_bundle # A partial token also uses the exact index.
     end
   end
-  alias location define_location
+  alias ranged_category define_ranged_category
   
   #  HIGHLY EXPERIMENTAL Not correctly working yet. Try it if you feel "beta".
   #
-  # Also a range search see #define_location, but on the earth's surface.
+  # Also a range search see #define_ranged_category, but on the earth's surface.
   #
   # Parameters:
   # * name: The name as used in #define_category.
@@ -128,7 +157,9 @@ class IndexAPI
   # * precision: Default 1 (20% error margin, very fast), up to 5 (5% error margin, slower) makes sense.
   # * from: The data category to take the data for this category from.
   #
-  def define_map_location name, radius, options = {}
+  # TODO Redo. Probably extract into define_latitude_category, define_longitude_category.
+  #
+  def define_map_location name, radius, options = {} # :nodoc:
     # The radius is given as if all the locations were on the equator.
     #
     # TODO Need to recalculate since not many locations are on the equator ;) This is just a prototype.
@@ -138,7 +169,7 @@ class IndexAPI
     # A degree on the equator is equal to ~111,319.9 meters.
     # So a km on the equator is equal to 0.00898312 degrees.
     #
-    define_location name, radius * 0.00898312, options
+    define_ranged_category name, radius * 0.00898312, options
   end
   alias map_location define_map_location
 end

data/lib/picky/indexed/index.rb

@@ -4,7 +4,7 @@ module Indexed
   #
   class Index
     
-    attr_reader :name, :result_type, :combinator, :categories
+    attr_reader :name, :result_identifier, :combinator, :categories
     
     delegate :load_from_cache,
              :to => :categories
@@ -12,7 +12,7 @@ module Indexed
     def initialize name, options = {}
       @name                     = name
       
-      @result_type              = options[:result_type] || name
+      @result_identifier        = options[:result_identifier] || name
       ignore_unassigned_tokens  = options[:ignore_unassigned_tokens] || false # TODO Move to query, somehow.
       
       @categories = Categories.new ignore_unassigned_tokens: ignore_unassigned_tokens

data/lib/picky/query/allocation.rb

@@ -4,13 +4,13 @@ module Query
   #
   class Allocation # :nodoc:all
 
-    attr_reader :count, :ids, :score, :combinations, :result_type
+    attr_reader :count, :ids, :score, :combinations, :result_identifier
     
     #
     #
-    def initialize combinations, result_type
-      @combinations = combinations
-      @result_type  = result_type
+    def initialize combinations, result_identifier
+      @combinations      = combinations
+      @result_identifier = result_identifier
     end
 
     def hash
@@ -61,7 +61,7 @@ module Query
     # Transform the allocation into result form.
     #
     def to_result
-      [self.result_type, self.score, self.count, @combinations.to_result, self.ids] if self.count > 0
+      [self.result_identifier, self.score, self.count, @combinations.to_result, self.ids] if self.count > 0
     end
 
     # Json representation of this allocation.

data/lib/picky/query/combinations.rb

@@ -62,10 +62,10 @@ module Query
       Performant::Array.memory_efficient_intersect id_arrays
     end
     
-    # Wrap the combinations into an allocation with the result_type
+    # Wrap the combinations into an allocation with the result_identifier.
     #
-    def pack_into_allocation result_type
-      Allocation.new self, result_type
+    def pack_into_allocation result_identifier
+      Allocation.new self, result_identifier
     end
     
     # Filters the tokens and identifiers such that only identifiers

data/lib/picky/query/weigher.rb

@@ -53,7 +53,7 @@ module Query
         
         # Wrap into a real combination.
         #
-        # expanded_combinations.map! { |expanded_combination| Combinations.new(expanded_combination).pack_into_allocation(index.result_type) }
+        # expanded_combinations.map! { |expanded_combination| Combinations.new(expanded_combination).pack_into_allocation(index.result_identifier) }
         
         # Add the possible allocations to the ones we already have.
         #
@@ -63,7 +63,7 @@ module Query
         # Add the wrapped possible allocations to the ones we already have.
         #
         previous_allocations + expanded_combinations.map! do |expanded_combination|
-          Combinations.new(expanded_combination).pack_into_allocation(index.result_type) # TODO Do not extract result_type. Remove pack_into_allocation.
+          Combinations.new(expanded_combination).pack_into_allocation(index.result_identifier) # TODO Do not extract result_identifier. Remove pack_into_allocation.
         end
       end)
     end

data/spec/lib/query/allocation_spec.rb

@@ -4,7 +4,7 @@ describe Query::Allocation do
   
   before(:each) do
     @combinations = stub :combinations
-    @allocation = Query::Allocation.new @combinations, :some_result_type
+    @allocation = Query::Allocation.new @combinations, :some_result_identifier
   end
   
   describe "eql?" do
@@ -34,7 +34,7 @@ describe Query::Allocation do
         @allocation.stub! :ids => :ids
       end
       it "represents correctly" do
-        @allocation.to_s.should == "Allocation: some_result_type, score, 10, combinations_result, ids"
+        @allocation.to_s.should == "Allocation: some_result_identifier, score, 10, combinations_result, ids"
       end
     end
   end
@@ -104,34 +104,34 @@ describe Query::Allocation do
   describe 'to_result' do
     context 'with few combinations' do
       before(:each) do
-        @allocation = Query::Allocation.new stub(:combinations, :ids => [1,2,3], :to_result => [:some_result]), :some_result_type
+        @allocation = Query::Allocation.new stub(:combinations, :ids => [1,2,3], :to_result => [:some_result]), :some_result_identifier
         @allocation.instance_variable_set :@score, :some_score
       end
       context 'with ids' do
         it 'should output an array of information' do
           @allocation.process! 20, 0
 
-          @allocation.to_result.should == [:some_result_type, :some_score, 3, [:some_result], [1, 2, 3]]
+          @allocation.to_result.should == [:some_result_identifier, :some_score, 3, [:some_result], [1, 2, 3]]
         end
       end
     end
     context 'with results' do
       before(:each) do
         combinations = stub :combinations, :ids => [1,2,3], :to_result => [:some_result1, :some_result2]
-        @allocation = Query::Allocation.new combinations, :some_result_type
+        @allocation = Query::Allocation.new combinations, :some_result_identifier
         @allocation.instance_variable_set :@score, :some_score
       end
       context 'with ids' do
         it 'should output an array of information' do
           @allocation.process! 20, 0
 
-          @allocation.to_result.should == [:some_result_type, :some_score, 3, [:some_result1, :some_result2], [1, 2, 3]]
+          @allocation.to_result.should == [:some_result_identifier, :some_score, 3, [:some_result1, :some_result2], [1, 2, 3]]
         end
       end
     end
     context 'without results' do
       before(:each) do
-        @allocation = Query::Allocation.new stub(:combinations, :ids => [], :to_result => []), :some_result_type
+        @allocation = Query::Allocation.new stub(:combinations, :ids => [], :to_result => []), :some_result_identifier
         @allocation.instance_variable_set :@score, :some_score
       end
       it 'should return nil' do
@@ -144,13 +144,13 @@ describe Query::Allocation do
 
   describe 'to_json' do
     before(:each) do
-      @allocation = Query::Allocation.new stub(:combination, :ids => [1,2,3,4,5,6,7], :to_result => [:some_result1, :some_result2]), :some_result_type
+      @allocation = Query::Allocation.new stub(:combination, :ids => [1,2,3,4,5,6,7], :to_result => [:some_result1, :some_result2]), :some_result_identifier
       @allocation.instance_variable_set :@score, :some_score
     end
     it 'should output the correct json string' do
       @allocation.process! 20, 0
 
-      @allocation.to_json.should == '["some_result_type","some_score",7,["some_result1","some_result2"],[1,2,3,4,5,6,7]]'
+      @allocation.to_json.should == '["some_result_identifier","some_score",7,["some_result1","some_result2"],[1,2,3,4,5,6,7]]'
     end
   end
 
@@ -164,9 +164,9 @@ describe Query::Allocation do
 
   describe "<=>" do
     it "should sort higher first" do
-      first = Query::Allocation.new [], :some_result_type
+      first = Query::Allocation.new [], :some_result_identifier
       first.instance_variable_set :@score, 20
-      second = Query::Allocation.new [], :some_result_type
+      second = Query::Allocation.new [], :some_result_identifier
       second.instance_variable_set :@score, 10
 
       first.<=>(second).should == -1
@@ -175,11 +175,11 @@ describe Query::Allocation do
 
   describe "sort!" do
     it "should sort correctly" do
-      first = Query::Allocation.new :whatever, :some_result_type
+      first = Query::Allocation.new :whatever, :some_result_identifier
       first.instance_variable_set :@score, 20
-      second = Query::Allocation.new :whatever, :some_result_type
+      second = Query::Allocation.new :whatever, :some_result_identifier
       second.instance_variable_set :@score, 10
-      third = Query::Allocation.new :whatever, :some_result_type
+      third = Query::Allocation.new :whatever, :some_result_identifier
       third.instance_variable_set :@score, 5
 
       allocations = [second, third, first]

data/spec/lib/query/combinations_spec.rb

@@ -12,10 +12,10 @@ describe 'Query::Combinations' do
   
   describe "pack_into_allocation" do
     it "return an Allocation" do
-      @combinations.pack_into_allocation(:some_result_type).should be_kind_of(Query::Allocation)
+      @combinations.pack_into_allocation(:some_result_identifier).should be_kind_of(Query::Allocation)
     end
-    it "returns an Allocation with specific result_type" do
-      @combinations.pack_into_allocation(:some_result_type).result_type.should == :some_result_type
+    it "returns an Allocation with specific result_identifier" do
+      @combinations.pack_into_allocation(:some_result_identifier).result_identifier.should == :some_result_identifier
     end
   end
   

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 1
-  - 6
-  version: 1.1.6
+  - 7
+  version: 1.1.7
 platform: ruby
 authors: 
 - Florian Hanke