picky 2.2.0 → 2.2.1

data/lib/picky/application.rb

@@ -13,14 +13,16 @@
 # will generate an example <tt>project_name/app/application.rb</tt> file for you
 # with some example code inside.
 #
-# == Index::Memory.new(name, source)
+# == Index::Memory.new(name)
 #
 # Next, define where your data comes from. You use the <tt>Index::Memory.new</tt> method for that:
-#   my_index = Index::Memory.new :some_index_name, some_source
+#   my_index = Index::Memory.new :some_index_name
 # You give the index a name (or identifier), and a source (see Sources), where its data comes from. Let's do that:
 #   class MyGreatSearch < Application
 #
-#     books = Index::Memory.new :books, Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
+#     books = Index::Memory.new :books do
+#       source Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
+#     end
 #
 #   end
 # Now we have an index <tt>books</tt>.
@@ -29,7 +31,7 @@
 #
 # Note that a Redis index is also available: Index::Redis.new.
 #
-# == index_instance.define_category(identifier, options = {})
+# == category(identifier, options = {})
 #
 # Picky needs us to define categories on the data.
 #
@@ -39,8 +41,10 @@
 # Let's go ahead and define a category:
 #   class MyGreatSearch < Application
 #
-#     books = Index::Memory.new :books, Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
-#     books.define_category :title
+#     books = Index::Memory.new :books do
+#       source   Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
+#       category :title
+#     end
 #
 #   end
 # Now we could already run the indexer:
@@ -52,7 +56,7 @@
 #
 # == Search.new(*indexes, options = {})
 #
-# We need somebody who asks the index (a Query object, also see http://github.com/floere/picky/wiki/Queries-Configuration). That works like this:
+# We need somebody who asks the index (a Query object, also see http://github.com/floere/picky/wiki/Queries-Configuration):
 #    books_search = Search.new books
 #
 # Now we have somebody we can ask about the index. But no external interface.
@@ -64,8 +68,10 @@
 # In full glory:
 #   class MyGreatSearch < Application
 #
-#     books = index :books, Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
-#     books.define_category :title
+#     books = index :books do
+#       source   Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
+#       category :title
+#     end
 #
 #     route %r{^/books$} => Search.new(books)
 #
@@ -82,19 +88,19 @@
 #
 # Maybe you don't find everything. We need to process the data before it goes into the index.
 #
-# == default_indexing(options = {})
+# == indexing(options = {})
 #
-# That's what the <tt>default_indexing</tt> method is for:
-#   default_indexing options
+# That's what the <tt>indexing</tt> method is for:
+#   indexing options
 # Read more about the options here: http://github.com/floere/picky/wiki/Indexing-configuration
 #
 # Same thing with the search text – we need to process that as well.
 #
-# == default_querying(options = {})
+# == searching(options = {})
 #
-# Analog to the default_indexing method, we use the <tt>default_querying</tt> method.
-#   default_querying options
-# Read more about the options here: http://github.com/floere/picky/wiki/Querying-Configuration
+# Analog to the indexing method, we use the <tt>searching</tt> method.
+#   searching options
+# Read more about the options here: http://github.com/floere/picky/wiki/Searching-Configuration
 #
 # And that's all there is. It's incredibly powerful though, as you can combine, weigh, refine to the max.
 #
@@ -109,35 +115,37 @@
 # Our example, fully fleshed out with indexing, querying, and weights:
 #   class MyGreatSearch < Application
 #
-#     default_indexing removes_characters: /[^a-zA-Z0-9\.]/,
-#                      stopwords: /\b(and|or|in|on|is|has)\b/,
-#                      splits_text_on: /\s/,
-#                      removes_characters_after_splitting: /\./,
-#                      substitutes_characters_with: CharacterSubstituters::WestEuropean.new,
-#                      normalizes_words: [
-#                        [/(.*)hausen/, 'hn'],
-#                        [/\b(\w*)str(eet)?/, 'st']
-#                      ]
-#
-#     default_querying removes_characters: /[^a-zA-Z0-9\s\/\-\,\&\"\~\*\:]/,
-#                      stopwords: /\b(and|the|of|it|in|for)\b/,
-#                      splits_text_on: /[\s\/\-\,\&]+/,
-#                      removes_characters_after_splitting: /\./,
-#                      substitutes_characters_with: CharacterSubstituters::WestEuropean.new,
-#                      maximum_tokens: 4
-#
-#     books = Index::Memory.new :books, Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
-#     books.define_category :title,
-#                           qualifiers: [:t, :title, :titre],
-#                           partial:    Partial::Substring.new(:from => 1),
-#                           similarity: Similarity::DoubleMetaphone.new(2)
-#     books.define_category :author,
-#                           partial: Partial::Substring.new(:from => -2)
-#     books.define_category :isbn
-#
-#     options = { :weights => { [:title, :author] => +3, [:author, :title] => -1 } }
-#
-#     route %r{^/books$} => Search.new(books, options)
+#     indexing removes_characters: /[^a-zA-Z0-9\.]/,
+#              stopwords: /\b(and|or|in|on|is|has)\b/,
+#              splits_text_on: /\s/,
+#              removes_characters_after_splitting: /\./,
+#              substitutes_characters_with: CharacterSubstituters::WestEuropean.new,
+#              normalizes_words: [
+#                [/(.*)hausen/, 'hn'],
+#                [/\b(\w*)str(eet)?/, 'st']
+#              ]
+#
+#     searching removes_characters: /[^a-zA-Z0-9\s\/\-\,\&\"\~\*\:]/,
+#               stopwords: /\b(and|the|of|it|in|for)\b/,
+#               splits_text_on: /[\s\/\-\,\&]+/,
+#               removes_characters_after_splitting: /\./,
+#               substitutes_characters_with: CharacterSubstituters::WestEuropean.new,
+#               maximum_tokens: 4
+#
+#     books = Index::Memory.new :books do
+#       source   Sources::CSV.new(:title, :author, :isbn, file:'app/library.csv')
+#       category :title,
+#                qualifiers: [:t, :title, :titre],
+#                partial:    Partial::Substring.new(:from => 1),
+#                similarity: Similarity::DoubleMetaphone.new(2)
+#       category :author,
+#                partial: Partial::Substring.new(:from => -2)
+#       category :isbn
+#     end
+#
+#     route %r{^/books$} => Search.new(books) do
+#       boost [:title, :author] => +3, [:author, :title] => -1
+#     end
 #
 #   end
 # That's actually already a full-blown Picky App!

data/lib/picky/index/base.rb

@@ -15,15 +15,15 @@ module Index
     #
     # === 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(...). Optional, can be defined in the block using #source.
     #
     # === Options
+    # * source: Where the data comes from, e.g. Sources::CSV.new(...). Optional, can be defined in the block using #source.
     # * 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.
-    # * tokenizer: The tokenizer to use for this index.
+    # * tokenizer: The tokenizer to use for this index. Optional, can be defined in the block using #indexing.
     #
     # Examples:
-    #   my_index = Index::Memory.new(:my_index, some_source) do
+    #   my_index = Index::Memory.new(:my_index, source: some_source) do
     #     category :bla
     #   end
     #
@@ -64,10 +64,10 @@ module Index
       raise ArgumentError.new(<<-NAME
 
 
-The index identifier (you gave "#{name}") for Index::Memory/Index::Redis should be a String/Symbol,
+The index identifier (you gave "#{name}") for Index::Memory/Index::Redis should be a Symbol/String,
 Examples:
-  Index::Memory.new(:my_cool_index, ...) # Recommended
-  Index::Redis.new("a-redis-index", ...)
+  Index::Memory.new(:my_cool_index) # Recommended
+  Index::Redis.new("a-redis-index")
 NAME
 
 
@@ -121,12 +121,12 @@ INDEX
 
     # Define an index tokenizer on the index.
     #
-    # Parameters are the exact same as for the default_indexing.
+    # Parameters are the exact same as for indexing.
     #
-    def define_indexing options = {}
+    def indexing options = {}
       internal_indexing.define_indexing options
     end
-    alias indexing define_indexing
+    alias define_indexing indexing
 
     # Define a source on the index.
     #
@@ -134,10 +134,10 @@ INDEX
     # anything responding to #each and returning objects that
     # respond to id and the category names (or the category from option).
     #
-    def define_source source
+    def source source
       internal_indexing.define_source source
     end
-    alias source define_source
+    alias define_source source
 
     # Defines a searchable category on the index.
     #
@@ -152,7 +152,7 @@ INDEX
     # * source: Use a different source than the index uses. If you think you need that, there might be a better solution to your problem. Please post to the mailing list first with your application.rb :)
     # * from: Take the data from the data category with this name. Example: You have a source Sources::CSV.new(:title, file:'some_file.csv') but you want the category to be called differently. The you use from: define_category(:similar_title, :from => :title).
     #
-    def define_category category_name, options = {}
+    def category category_name, options = {}
       category_name = category_name.to_sym
 
       indexing_category = internal_indexing.define_category category_name, options
@@ -162,11 +162,10 @@ INDEX
 
       self
     end
-    alias category define_category
+    alias define_category category
 
-    #  HIGHLY EXPERIMENTAL Try if you feel "beta" ;)
-    #
-    # Make this category range searchable with a fixed range. If you need other ranges, define another category with a different range value.
+    # 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
@@ -174,22 +173,27 @@ INDEX
     # 45, 46, or 47.2, 48.9, in a range of 2 around 47, so (45..49).
     #
     # Then you use:
-    #  my_index.define_ranged_category :values_inside_1_100, 2
+    #  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_ranged_category :values_inside_1_100, 2, precision: 5
+    #   Index::Memory.new :range do
+    #     ranged_category :values_inside_1_100, 2, precision: 5
+    #   end
     #
     # This will force Picky to maximally be wrong 5% of the given range value
     # (5% of 2 = 0.1) instead of the default 20% (20% of 2 = 0.4).
     #
-    # We suggest not to use much more than 5 as a higher precision is more performance intensive for less and less precision gain.
+    # We suggest not to use much more than 5 as a higher precision is more
+    # performance intensive for less and less precision gain.
     #
     # == Protip 1
     #
     # Create two ranged categories to make an area search:
-    #   index.define_ranged_category :x, 1
-    #   index.define_ranged_category :y, 1
+    #   Index::Memory.new :area do
+    #     ranged_category :x, 1
+    #     ranged_category :y, 1
+    #   end
     #
     # Search for it using for example:
     #   x:133, y:120
@@ -223,7 +227,7 @@ INDEX
     # * 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_ranged_category category_name, range, options = {}
+    def ranged_category category_name, range, options = {}
       precision = options[:precision] || 1
 
       options = { partial: Partial::None.new }.merge options
@@ -233,17 +237,18 @@ INDEX
         Internals::Indexed::Wrappers::Category::Location.install_on indexed_category, range, precision
       end
     end
-    alias ranged_category define_ranged_category
+    alias define_ranged_category ranged_category
 
     # HIGHLY EXPERIMENTAL Not correctly working yet. Try it if you feel "beta".
     #
-    # Also a range search see #define_ranged_category, but on the earth's surface.
+    # Also a range search see #ranged_category, but on the earth's surface.
     #
     # Parameters:
-    # * name: The name as used in #define_category.
+    # * lat_name: The latitude's name as used in #define_category.
+    # * lng_name: The longitude's name as used in #define_category.
     # * radius: The distance (in km) around the query point which we search for results.
     #
-    # Note: Picky uses a square, not a circle. We hope that's ok for most usages.
+    # Note: Picky uses a square, not a circle. That should be ok for most usages.
     #
     #  -----------------------------
     #  |                           |
@@ -261,23 +266,40 @@ INDEX
     #
     # 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.
+    # * lat_from: The data category to take the data for the latitude from.
+    # * lng_from: The data category to take the data for the longitude from.
     #
-    # TODO Redo. Will have to write a wrapper that combines two categories that are indexed simultaneously.
+    # TODO Will have to write a wrapper that combines two categories that are
+    #      indexed simultaneously, since lat/lng are correlated.
     #
-    def define_map_location name, radius, options = {} # :nodoc:
-      # The radius is given as if all the locations were on the equator.
+    def geo_categories lat_name, lng_name, radius, options = {} # :nodoc:
+
+      # Extract lat/lng specific options.
       #
-      # TODO Need to recalculate since not many locations are on the equator ;) This is just a prototype.
+      lat_from = options.delete :lat_from
+      lng_from = options.delete :lng_from
+
+      # One can be a normal ranged_category.
+      #
+      ranged_category lat_name, radius*0.00898312, options.merge(from: lat_from)
+
+      # The other needs to adapt the radius depending on the one.
+      #
+      # Depending on the latitude, the radius of the longitude
+      # needs to enlarge, the closer we get to the pole.
+      #
+      # In our simplified case, the radius is given as if all the
+      # locations were on the 45 degree line.
       #
       # This calculates km -> longitude (degrees).
       #
-      # A degree on the equator is equal to ~111,319.9 meters.
-      # So a km on the equator is equal to 0.00898312 degrees.
+      # A degree on the 45 degree line is equal to ~222.6398 km.
+      # So a km on the 45 degree line is equal to 0.01796624 degrees.
       #
-      define_ranged_category name, radius * 0.00898312, options
+      ranged_category lng_name, radius*0.01796624, options.merge(from: lng_from)
+
     end
-    alias map_location define_map_location
+    alias define_geo_categories geo_categories
   end
 
 end

data/lib/picky/internals/indexed/bundle/base.rb

@@ -2,8 +2,6 @@ module Internals
 
   module Indexed # :nodoc:all
 
-    # TODO Rewrite.
-    #
     # A Bundle is a number of indexes
     # per [index, category] combination.
     #

data/lib/picky/internals/indexed/categories.rb

@@ -105,8 +105,6 @@ module Internals
       #       (Also none of the categories matched, but the ignore unassigned
       #       tokens option is true)
       #
-      # TODO Could use Combinations class here and remove the inject.
-      #
       def possible_for token, preselected_categories = nil
         possible = (preselected_categories || possible_categories(token)).inject([]) do |combinations, category|
           combination = category.combination_for token

data/lib/picky/internals/indexed/index.rb

@@ -12,8 +12,6 @@ module Internals
                :analyze,
                :to => :categories
 
-      # TODO Externalize?
-      #
       def initialize name, options = {}
         @name                     = name
 
@@ -24,8 +22,6 @@ module Internals
         @categories = Categories.new ignore_unassigned_tokens: ignore_unassigned_tokens
       end
 
-      # TODO Doc. Externalize?
-      #
       def define_category category_name, options = {}
         options = default_category_options.merge options
 

data/lib/picky/internals/indexed/wrappers/exact_first.rb

@@ -4,15 +4,11 @@ module Internals
   #
   module Indexed
 
-    # TODO Spec
-    #
     module Wrappers
 
       # This index combines an exact and partial index.
       # It serves to order the results such that exact hits are found first.
       #
-      # TODO Need to use the right subtokens. Bake in?
-      #
       class ExactFirst < Indexed::Bundle::Base
 
         delegate :similar,
@@ -42,8 +38,6 @@ module Internals
             new index_or_category
           end
         end
-        # TODO Do not extract categories!
-        #
         def self.wrap_each_of categories
           categories.categories.collect! { |category| new(category) }
         end

data/lib/picky/internals/indexers/serial.rb

@@ -6,8 +6,6 @@ module Indexers
   #
   # Note: It is called serial since it indexes each
   #
-  # FIXME Giving the serial a category would be enough, since it already contains an index!
-  #
   class Serial < Base
 
     attr_reader :category
@@ -24,22 +22,13 @@ module Indexers
       @tokenizer ||= category.tokenizer
     end
 
+    # Harvest the data from the source, tokenize,
+    # and write to an intermediate "prepared index" file.
+    #
     def process
       comma   = ?,
       newline = ?\n
 
-      # TODO Move open to config?
-      #
-      # @category.prepared_index do |file|
-      #   source.harvest(@index, @category) do |indexed_id, text|
-      #     tokenizer.tokenize(text).each do |token_text|
-      #       next unless token_text
-      #       file.buffer indexed_id << comma << token_text << newline
-      #     end
-      #     file.write_maybe
-      #   end
-      # end
-      #
       local_tokenizer = tokenizer
       category.prepared_index_file do |file|
         result = []

data/lib/picky/internals/indexing/bundle/redis.rb

@@ -3,26 +3,26 @@
 module Internals
 
   module Indexing # :nodoc:all
-  
+
     module Bundle
-    
-      # The memory version dumps its generated indexes to disk
-      # (mostly JSON) to load them into memory on startup.
+
+      # The Redis version dumps its generated indexes to
+      # the Redis backend.
       #
       class Redis < Base
-      
+
         attr_reader :backend
-      
-        def initialize name, configuration, *args
-          super name, configuration, *args
-        
-          @backend = Internals::Index::Redis.new name, configuration # TODO Needed?
+
+        def initialize name, category, *args
+          super name, category, *args
+
+          @backend = Internals::Index::Redis.new name, category
         end
-    
+
       end
-    
+
     end
-  
+
   end
-  
+
 end

data/lib/picky/internals/query/tokens.rb

@@ -44,10 +44,12 @@ module Internals
       #  [combination, combination]               # of token 3
       # ]
       #
-      def possible_combinations_in type
+      def possible_combinations_in index
         @tokens.inject([]) do |combinations, token|
-          possible_combinations = token.possible_combinations_in type
+          possible_combinations = token.possible_combinations_in index
 
+          # TODO Could move the ignore_unassigned_tokens here!
+          #
           # Note: Optimization for ignoring tokens that allocate to nothing and
           # can be ignored.
           # For example in a special search, where "florian" is not

data/lib/picky/internals/tokenizers/base.rb

@@ -117,7 +117,7 @@ Case sensitive?            #{@case_sensitive ? "Yes." : "-"}
 
       # Reject tokens after tokenizing based on the given criteria.
       #
-      # Note: Currently only for indexing. TODO Redesign and write for both!
+      # Note: Currently only for indexing.
       #
       def reject_token_if &condition
         @reject_condition = condition

data/spec/aux/picky/cli_spec.rb

@@ -6,8 +6,6 @@ require 'spec_helper'
 #
 require File.expand_path '../../../../aux/picky/cli', __FILE__
 
-# TODO Finish this prototype Spec, redesign.
-#
 describe Picky::CLI do
   
   describe '.mapping' do

data/spec/lib/index/base_spec.rb

@@ -53,6 +53,15 @@ ERROR
   context 'unit' do
     let(:api) { described_class.new :some_index_name, source: some_source }
     
+    describe 'geo_categories' do
+      it 'delegates correctly' do
+        api.should_receive(:ranged_category).once.with :some_lat, 0.00898312, from: :some_lat_from
+        api.should_receive(:ranged_category).once.with :some_lng, 0.01796624, from: :some_lng_from
+        
+        api.geo_categories :some_lat, :some_lng, 1, :lat_from => :some_lat_from, :lng_from => :some_lng_from
+      end
+    end
+    
     describe 'define_source' do
       it 'delegates to the internal indexing' do
         indexing = stub :indexing

data/spec/lib/internals/indexed/wrappers/exact_first_spec.rb

@@ -11,22 +11,22 @@ describe Internals::Indexed::Wrappers::ExactFirst do
   end
   
   describe "self.wrap" do
-    context "type" do
-      # FIXME
-      #
-      # it "wraps each category" do
-      #   type = Index::Type.new :type_name
-      #   type.define_category :some_category
-      #   
-      #   Index::Wrappers::ExactFirst.wrap type
-      #   
-      #   type.categories.should be_kind_of(Index::Wrappers::ExactFirst)
-      # end
-      it "returns the type" do
-        type = Internals::Indexed::Index.new :type_name
-        type.define_category :some_category
+    context "index" do
+      it "wraps each category" do
+        index = Internals::Indexed::Index.new :index_name
+        index.define_category :some_category
+        
+        Internals::Indexed::Wrappers::ExactFirst.wrap index
+        
+        index.categories.categories.each do |category|
+          category.should be_kind_of(Internals::Indexed::Wrappers::ExactFirst)
+        end
+      end
+      it "returns the index" do
+        index = Internals::Indexed::Index.new :index_name
+        index.define_category :some_category
         
-        described_class.wrap(type).should == type
+        described_class.wrap(index).should == index
       end
     end
     context "category" do

metadata

@@ -2,7 +2,7 @@
 name: picky
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 2.2.0
+  version: 2.2.1
 platform: ruby
 authors: 
 - Florian Hanke
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-14 00:00:00 +10:00
+date: 2011-04-15 00:00:00 +10:00
 default_executable: picky
 dependencies: 
 - !ruby/object:Gem::Dependency