easyredis 0.0.3 → 0.0.4

data/README.md

@@ -6,18 +6,21 @@ Redis is a very fast key-value store that supports data structures like lists, (
 
 ## Installation
 
-You can get the source with git:
+You can just grab the gem and you're good to go:
+
+    $ gem install easyredis
+
+Or, you can get the source with git:
 
     $ git clone git://github.com/alecbenzer/easyredis.git
 
 or just download and extract a tar archive with the Downloads button.
 
-Once you have the source, run:
+Once you have the source, you can run:
 
-    $ rake
-    $ gem install pkg/easyredis-x.x.x.gem
-
-Where x.x.x is the current version number.
+    $ rake manifest
+    $ rake build_gemspec
+    $ rake install easyredis.gemspec
 
 ## Basics
 
@@ -69,5 +72,21 @@ We can now sort our posts by title:
 
 And also search:
 
-    Post.search_by(:title,"A common title")  # all posts with this title
-    Post.find_by(:title,"My First Post")  # just one post
+    Post.search_by :title, "A common title"  # all posts with this title
+    Post.find_by :title, "My First Post"  # just one post
+
+## Text Search and Completions
+
+We could have defined Post like this:
+
+    class Post < EasyRedis::Model
+      field :title
+      field :body
+
+      text_search :title
+    end
+
+Now we can perform text searches and completions against our title field:
+
+    Post.matches(:title,"Fir")  # titles that begin with "Fir"
+    Post.match(:title,"First")  # posts whose titles contain "First"

data/Rakefile

@@ -2,21 +2,20 @@ require 'rubygems'
 require 'rake'
 require 'echoe'
 
-Echoe.new('easyredis','0.0.3') do |p|
+Echoe.new('easyredis','0.0.4') do |p|
   p.description = "simple framework designed to make using redis as a database simpler"
   p.url = "https://github.com/alecbenzer/easyredis"
   p.author = "Alec Benzer"
   p.email = "alecbezer @nospam@ gmail.com"
   p.ignore_pattern = ["*.rdb"]
-  p.development_dependencies = ["redis >=2.1.1","activesupport >=3.0.0"]
+  p.development_dependencies = ["redis >=2.1.1"]
 end
 
 
 require 'benchmark'
 require './tests/test'
 
-def rand_name
-  length = 2
+def rand_name(length=2)
   chars = []
   length.times { chars << (rand(26) + 65).chr }
   chars.join
@@ -26,17 +25,17 @@ end
 namespace :bm do
   task :clear do
     puts "destroying #{Man.count} previous entries"
-    Benchmark.bm do |bm|
-      bm.report { Man.destroy_all }
-    end
+    time = Benchmark.measure { Man.destroy_all }
+    puts time.format
   end
 
   task :add do
     count = ENV["count"] ? ENV["count"].to_i : 25000
     puts "adding #{count} new entries"
     time = Benchmark::Tms.new
+    length = Math.log(3*count,26).round
     count.times do
-      name = rand_name
+      name = rand_name(length)
       age = rand(100)
       time += Benchmark.measure { m = Man.new ; m.name = name ; m.age = age }
     end
@@ -48,9 +47,10 @@ namespace :bm do
   task :search do
     puts "searching #{Man.count} entries by a particular name"
     name = Man.rand.name
-    Benchmark.bm do |bm|
-      bm.report { Man.search_by(:name,name) }
-    end
+    count = -1
+    time = Benchmark.measure { count = Man.search_by(:name,name).count }
+    puts "retrived #{count} records in:"
+    puts (time*1000).format
   end
 
   task :singlesearch do
@@ -60,9 +60,9 @@ namespace :bm do
     t1 = Benchmark.measure { Man.search(:age => age) }
     t2 = Benchmark.measure { Man.search_by(:age,age) }
     puts "Model#search:"
-    puts t1.format
+    puts (t1*1000).format
     puts "Model#search_by:"
-    puts t2.format
+    puts (t2*1000).format
     puts "search is #{((t1.real/t2.real) - 1)*100}% slower"
   end
 
@@ -73,15 +73,14 @@ namespace :bm do
     count = 0
     time = Benchmark.measure { count = Man.search(:name => name, :age => age).size }
     puts "retrived #{count} out of #{Man.count} entries in:"
-    puts time.format
+    puts (time*1000).format
   end
 
   task :find do
     puts "finding one of #{Man.count} entries by name"
     name = Man.rand.name
-    Benchmark.bm do |bm|
-      bm.report { Man.find_by(:name,name) }
-    end
+    time = Benchmark.measure { Man.find_by(:name,name) }
+    puts (time*1000).format
   end
 
 end

data/easyredis.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{easyredis}
-  s.version = "0.0.3"
+  s.version = "0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alec Benzer"]
-  s.date = %q{2011-02-06}
+  s.date = %q{2011-02-07}
   s.description = %q{simple framework designed to make using redis as a database simpler}
   s.email = %q{alecbezer @nospam@ gmail.com}
   s.extra_rdoc_files = ["README.md", "lib/easyredis.rb"]
@@ -23,13 +23,10 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<redis>, [">= 2.1.1"])
-      s.add_development_dependency(%q<activesupport>, [">= 3.0.0"])
     else
       s.add_dependency(%q<redis>, [">= 2.1.1"])
-      s.add_dependency(%q<activesupport>, [">= 3.0.0"])
     end
   else
     s.add_dependency(%q<redis>, [">= 2.1.1"])
-    s.add_dependency(%q<activesupport>, [">= 3.0.0"])
   end
 end

data/lib/easyredis.rb

@@ -7,7 +7,6 @@
 
 require 'redis'
 require 'set'
-require 'active_support/inflector'
 
 
 # main EasyRedis module which
@@ -16,6 +15,9 @@ module EasyRedis
   
   # generate a 'score' for a string
   # used for storing it in a sorted set
+  #
+  # This method effectively turns a string into a base 27 floating point number,
+  # where 0 corresponds to no letter, 1 to A, 2 to B, etc.
   def self.string_score(str)
     str = str.downcase
     mult = 1.0
@@ -29,11 +31,19 @@ module EasyRedis
 
   # gets a score for a generic object
   #
-  # Uses EasyRedis#string_score if the object is a string,
-  # and just returns the object otherwise (presumably its a number)
+  # The score is determined as follows:
+  # First, if the object is a string, string_score is used to get its score.
+  # Otherwise, we try calling the following methods on the object in turn, returning the first that works: score, to_f, to_i.
+  # If none of those work, we simply return the object itself.
   def self.score(obj)
     if obj.is_a? String
       string_score(obj)
+    elsif obj.respond_to? "score"
+      obj.score
+    elsif obj.respond_to? "to_f"
+      obj.to_f
+    elsif obj.respond_to? "to_i"
+      obj.to_i
     else
       obj
     end
@@ -62,6 +72,17 @@ module EasyRedis
     end
   end
 
+  # exception that indicates that the given field has not been indexed for text-searching
+  class FieldNotTextSearchable < RuntimeError
+    def initialize(field)
+      @message = "field '#{field.to_s}' not text-searchable"
+    end
+    
+    def to_s
+      @message
+    end
+  end
+
   # exception that indicated an unknown ordering option was encountered
   class UnknownOrderOption < RuntimeError
     def initialize(opt)
@@ -73,23 +94,14 @@ module EasyRedis
     end
   end
 
-  # class representing a sort
-  class Sort
+  # class representing a generic collection
+  class Collection
     include Enumerable
 
-    # initialize the sort with a specific field, ordering option, and model
-    def initialize(field,order,klass)
-      raise EasyRedis::FieldNotSortable, field  unless klass.sortable?(field) 
-      raise EasyRedis::UnknownOrderOption, order  unless [:asc,:desc].member? order
-      @field = field
-      @order = order
-      @klass = klass
-    end
-
     # access elements in this sort
     #
-    # Work's like ruby's Array#[]. It can take a specific index, a range, or an offset, amount pair.
-    # Calling this method will actually query the redis server for ids
+    # Work's like an Array's [] method. It can take a specific index, a range, or an offset and an amount/limit.
+    # This method uses the underlying access method, which handles the actual retrival.
     def [](index,limit=nil)
       if limit
         offset = index
@@ -101,36 +113,12 @@ module EasyRedis
       end
     end
 
-    # helper method for []
-    #
-    # takes a range and returns corresponding elements
-    def access(range)
-      a = range.begin
-      b = range.end
-      b -= 1 if index.exclude_end?
-      ids = []
-      if @order == :asc
-        ids = EasyRedis.redis.zrange(@klass.sort_prefix(@field),a,b)
-      elsif @order == :desc
-        ids = EasyRedis.redis.zrevrange(@klass.sort_prefix(@field),a,b)
-      end
-      ids.map{|i|@klass.new(i)}
-    end
-
-    # iterate through all members of this sort
+    # iterate through all members of this collection
     def each
       self[0..-1].each { |o| yield o }
     end
 
-    # return the number of elements in this sort
-    #
-    # As of now, idential to the Model's #count method.
-    # This method is explicility defined here to overwrite the default one in Enumerable, which iterates through all the entries to count them
-    def count
-      EasyRedis.zcard(@klass.sort_prefix(@field))
-    end
-
-    # return the fist element of this sort, or the first n elements, if n is given
+    # return the fist element of this collection, or the first n elements, if n is given
     def first(n = nil)
       if n
         self[0,n]
@@ -139,6 +127,7 @@ module EasyRedis
       end
     end
 
+    # return the last element of this collection, or the last n elements, if n is given
     def last(n = nil)
       if n
         self[-n..-1]
@@ -147,16 +136,66 @@ module EasyRedis
       end
     end
 
+    private
+
+    # access the elements corresponding to the given range
+    #
+    # meant to be overridden in child classes
+    def access(range)
+      []
+    end
+
+  end
+
+  # class representing a sort
+  class Sort < Collection
+
+    # initialize the sort with a specific field, ordering option, and model
+    def initialize(field,order,klass)
+      raise EasyRedis::FieldNotSortable, field  unless klass.sortable?(field) 
+      raise EasyRedis::UnknownOrderOption, order  unless [:asc,:desc].member? order
+      @field = field
+      @order = order
+      @klass = klass
+    end
+
+    # return the number of elements in this sort
+    #
+    # As of now, idential to the Model's count method.
+    # This method is explicility defined here to overwrite the default one in Enumerable, which iterates through all the entries to count them, which is much slower than a ZCARD command
+    def count
+      EasyRedis.zcard(@klass.sort_key(@field))
+    end
+
     def inspect
       "#<EasyRedis::Sort model=#{@klass.name}, field=#{@field.to_s}, order=#{@order.to_s}>"
     end
 
+    private
+
+    # takes a range and returns corresponding elements
+    def access(range)
+      a = range.begin
+      b = range.end
+      b -= 1 if range.exclude_end?
+      ids = []
+      if @order == :asc
+        ids = EasyRedis.redis.zrange(@klass.sort_key(@field),a,b)
+      elsif @order == :desc
+        ids = EasyRedis.redis.zrevrange(@klass.sort_key(@field),a,b)
+      end
+      ids.map{|i|@klass.new(i)}
+    end
+
   end
 
 
   # class representing a data model
   # you want to store in redis
   class Model
+    
+    @@sorts = []
+    @@text_searches = []
 
     # add a field to the model
     def self.field(name)
@@ -180,22 +219,33 @@ module EasyRedis
         EasyRedis.redis.hset(key_name,name,Marshal.dump(val))
         instance_variable_set(instance_var,val)
 
-        if @@sorts.member? name.to_sym
-          # score = val.is_a?(String) ? EasyRedis.string_score(val) : val
-          EasyRedis.redis.zadd(sort_prefix(name),EasyRedis.score(val),@id)
+        if self.class.sortable? name.to_sym
+          EasyRedis.redis.zadd(sort_key(name),EasyRedis.score(val),@id)
+        end
+
+        if self.class.text_search? name.to_sym
+          val.split.each do |term|
+            EasyRedis.redis.zadd term_key(name,term), created_at.to_i, id
+            EasyRedis.redis.zadd terms_key(name), EasyRedis.score(term), term
+          end
         end
       end
     end
 
     # index a field to be sorted/searched
     def self.sort_on(field)
-      @@sorts ||= []
       @@sorts << field.to_sym
     end
 
+    # index a field for text searching
+    def self.text_search(field)
+      @@text_searches << field.to_sym
+      sort_on(field) unless sortable? field
+    end
+
     # returns number of instances of this model
     def self.count
-      EasyRedis.redis.zcard(prefix.pluralize)
+      EasyRedis.redis.zcard(prefix)
     end
 
     # get all instances of this model
@@ -204,27 +254,33 @@ module EasyRedis
       self.sort_by :created_at, options
     end
 
+    # same as all.first
     def self.first(n = nil)
       self.all.first(n)
     end
 
+    # same as all.last
     def self.last(n = nil)
       self.all.last(n)
     end
 
+    # returns a random entry of this model
     def self.rand
       self[Kernel.rand(self.count)]
     end
 
     # find an instance of this model based on its id
     def self.find(id)
-      if EasyRedis.redis.zscore(prefix.pluralize,id)
+      if EasyRedis.redis.zscore(prefix,id)
         new(id)
       else
         nil
       end
     end
 
+    # access entries of this model based on time
+    # 
+    # same as all.[]
     def self.[](index,amt=nil)
       self.all[index,amt]
     end
@@ -234,7 +290,7 @@ module EasyRedis
       raise EasyRedis::FieldNotSortable, field unless @@sorts.member? field.to_sym
       scr = EasyRedis.score(val)
       # options[:limit] = [0,options[:limit]] if options[:limit]
-      ids = EasyRedis.redis.zrangebyscore(sort_prefix(field),scr,scr,proc_options(options))
+      ids = EasyRedis.redis.zrangebyscore(sort_key(field),scr,scr,proc_options(options))
       ids.map{|i| new(i) }
     end
 
@@ -243,12 +299,15 @@ module EasyRedis
       search_by(field,val,:limit => 1).first
     end
 
+    # search the model based on multiple parameters
+    #
+    # takes a hash of field => value pairs
     def self.search(params)
       return search_by(*params.first) if params.size == 1  # comment out for benchmarking purposes
       result_set = nil
       params.each do |field,value|
         scr = EasyRedis.score(value)
-        ids = EasyRedis.redis.zrangebyscore(sort_prefix(field),scr,scr)
+        ids = EasyRedis.redis.zrangebyscore(sort_key(field),scr,scr)
         result_set = result_set ? (result_set & Set.new(ids)) : Set.new(ids)
       end
       result_set.map{|i|new(i)}
@@ -259,39 +318,42 @@ module EasyRedis
       EasyRedis::Sort.new(field,options[:order],self)
     end
 
-    # gives all values for the given field that begins with str
+    # gives all values for the given field that begin with str
     #
-    # This method is currently iterates through all existing entries. It is therefore very slow and should probably not be used at this time.
+    # The field must have been indexed with text_search.
     def self.matches(field,str)
+      raise FieldNotTextSearchable, field unless self.text_search? field
       scr = EasyRedis.score(str)
       a,b = scr, scr+1/(27.0**str.size)
-      ids = EasyRedis.redis.zrangebyscore(sort_prefix(field), "#{a}", "(#{b}")
-      s = Set.new  
-      ids.each{|i| s << new(i).send(field.to_s) }
-      s.to_a
+      EasyRedis.redis.zrangebyscore(terms_key(field), "#{a}", "(#{b}")
     end
 
-    # searches for all entries where field begins with str
+    # searches for all entries where field contains the string str
     #
-    # works with string fields that have been indexed with sort_on
+    # The string must appear exactly as a term in field's value. To search based on the beginning of a term, you can combine this method with matches.
+    # The field must have been indexed with text_search.
     def self.match(field,str, options = {})
-      raise EasyRedis::FieldNotSortable, filename unless @@sorts.member? field
-      scr = EasyRedis.score(str)
-      a,b = scr, scr+1/(27.0**str.size)
-      ids = EasyRedis.redis.zrangebyscore(sort_prefix(field), "#{a}", "(#{b}", proc_options(options))
+      raise EasyRedis::FieldNotTextSearchable, filename unless text_search? field
+      ids = EasyRedis.redis.zrange(term_key(field,str), 0, -1, proc_options(options))
       ids.map{|i| new(i)}
     end
 
     # indicates whether field has been indexed with sort_on
     def self.sortable?(field)
-      @@sorts.member? field or field.to_sym == :created_at
+      @@sorts and (@@sorts.member? field or field.to_sym == :created_at)
+    end
+
+    # indicates whether field has been indexed with text_search
+    def self.text_search?(field)
+      @@text_searches and @@text_searches.member?(field)
     end
 
     # destroy all instances of this model
     def self.destroy_all
       all.each {|x| x.destroy}
-      @@sorts.each {|field| EasyRedis.redis.del(sort_prefix(field)) }
-      EasyRedis.redis.del(prefix.pluralize)
+      @@sorts.each {|field| EasyRedis.redis.del(sort_key(field)) }
+      @@text_searches.each {|field| EasyRedis.redis.del(terms_key(field)) }
+      EasyRedis.redis.del(prefix)
       EasyRedis.redis.del(prefix + ":next_id")
     end
 
@@ -303,20 +365,20 @@ module EasyRedis
     #
     # If no id is passed, one is generated for you.
     # Otherwise, sets the id field to the passed id, but does not check to see if it is a valid id for this model.
-    # Users should use Model#find or Model#[] when retiving models by id, as these check for valid ids.
+    # Users should use find when retiving models by id, as these check for valid ids.
     def initialize(id=nil)
       if id
         @id = id
       else
         @id = EasyRedis.redis.incr(prefix + ':next_id')
-        EasyRedis.redis.zadd(prefix.pluralize,Time.now.to_i,@id)
+        EasyRedis.redis.zadd(prefix,Time.now.to_i,@id)
         @id
       end
     end
 
     # get the creation time of an entry
     def created_at
-      Time.at(EasyRedis.redis.zscore(prefix.pluralize,@id).to_i)
+      Time.at(EasyRedis.redis.zscore(prefix,@id).to_i)
     end
 
     # directly access a field of this entry's redis hash
@@ -339,7 +401,7 @@ module EasyRedis
 
     # remove the entry
     def destroy
-      EasyRedis.redis.zrem(prefix.pluralize,@id)
+      EasyRedis.redis.zrem(prefix,@id)
       EasyRedis.redis.del(key_name)
     end
 
@@ -362,8 +424,9 @@ module EasyRedis
 
     private 
 
+    # generate a temporary key name associated with this model
     def self.get_temp_key
-      i = EasyRedis.redis.incr prefix.pluralize + ':next_tmp_id'
+      i = EasyRedis.redis.incr "#{prefix}:next_tmp_id"
       "#{name}:tmp_#{i}"
     end
 
@@ -377,20 +440,36 @@ module EasyRedis
       self.name.downcase
     end
 
-    def self.sort_prefix(field)
+    def self.sort_key(field)
       if field == :created_at
-        prefix.pluralize
+        prefix
       else
-        prefix.pluralize + ':sort_' + field.to_s
+        "#{prefix}:sort_#{field.to_s}"
       end
     end
 
+    def self.terms_key(field)
+      "#{prefix}:terms_#{field.to_s}"
+    end
+
+    def self.term_key(field,term)
+      "#{prefix}:term_#{field}:#{term}"
+    end
+
     def prefix
       self.class.prefix
     end
 
-    def sort_prefix(field)
-      self.class.sort_prefix(field)
+    def sort_key(field)
+      self.class.sort_key(field)
+    end
+
+    def terms_key(field)
+      self.class.terms_key(field)
+    end
+
+    def term_key(field,term)
+      self.class.term_key(field,term)
     end
   end
 end

data/tests/test.rb

@@ -4,7 +4,7 @@ class Man < EasyRedis::Model
   field :name
   field :age
 
-  sort_on :name
+  text_search :name
   sort_on :age
 end
 

metadata

@@ -2,7 +2,7 @@
 name: easyredis
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Alec Benzer
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-06 00:00:00 -05:00
+date: 2011-02-07 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -24,17 +24,6 @@ dependencies:
         version: 2.1.1
   type: :development
   version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: activesupport
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 3.0.0
-  type: :development
-  version_requirements: *id002
 description: simple framework designed to make using redis as a database simpler
 email: alecbezer @nospam@ gmail.com
 executables: []