redis-objects 0.1.2 → 0.2.0

data/README.rdoc

@@ -6,97 +6,43 @@ the point.
 The killer feature of Redis that it allows you to perform atomic operations
 on _individual_ data structures, like counters, lists, and sets. You can then use
 these *with* your existing ActiveRecord/DataMapper/etc models, or in classes that have
-nothing to do with an ORM or even a database. That's where this gem comes in.
+nothing to do with an ORM or even a database.  This gem maps Ezra's +redis+ library
+to Ruby objects to make use seamless.
 
 This gem originally arose out of a need for high-concurrency atomic operations;
 for a fun rant on the topic, see
 {ATOMICITY}[http://github.com/nateware/redis-objects/blob/master/ATOMICITY.rdoc],
 or scroll down to "Atomicity" in this README.
 
-There are two ways to use Redis::Objects, either as an +include+ in a class, or
-by using +new+ with the type of data structure you want to create.
+There are two ways to use Redis::Objects, either as an +include+ in a model class,
+or by using +new+ with the type of data structure you want to create.
 
 == Installation
 
     gem install gemcutter
     gem tumble
     gem install redis-objects
-   
-== Example 1: Class Usage
 
-=== Initialization
-
-    # If on Rails, config/initializers/redis.rb is a good place for this
-    require 'redis'
-    require 'redis/objects'
-    Redis::Objects.redis = Redis.new(:host => 127.0.0.1, :port => 6379)
-
-=== Model Class
+== Example 1: Individual Usage
 
-Include in any type of class:
-
-    class Team < ActiveRecord::Base
-      include Redis::Objects
-      
-      counter :hits
-      counter :runs
-      counter :outs
-      counter :inning, :start => 1
-      list :on_base
-      set :outfielders
-      value :at_bat
-    end
-    
-Familiar Ruby array operations Just Work (TM):
-
-    @team = Team.find(1)
-    @team.on_base << 'player1'
-    @team.on_base << 'player2'
-    @team.on_base << 'player3'
-    @team.on_base    # ['player1', 'player2']
-    @team.on_base.pop
-    @team.on_base.shift
-    @team.on_base.length  # 1
-    @team.on_base.delete('player3')
-
-Sets work like the Ruby {Set}[http://ruby-doc.org/core/classes/Set.html] class:
-    
-    @team.outfielders << 'outfielder1' << 'outfielder1'
-    @team.outfielders << 'outfielder2'
-    @team.outfielders  # ['outfielder1', 'outfielder2']
-    @team.outfielders.each do |player|
-      puts player
-    end
-    player = @team.outfielders.detect{|of| of == 'outfielder2'}
-
-Note counters cannot be assigned to, only incremented/decremented:
-
-    @team.hits.increment  # or incr
-    @team.hits.decrement  # or decr
-    @team.runs = 4        # exception
-    @team.runs += 1       # exception
-
-It would be cool to get that last one working, but Ruby's implementation of +=
-is problematic.
-
-== Example 2: Instance Usage
-
-Each data type can be used independently.
+There is a Ruby object that maps to each Redis type.
 
 === Initialization
 
-Can follow the +$redis+ global variable pattern:
+You can either set the $redis global variable to your Redis handle:
 
     $redis = Redis.new(:host => 'localhost', :port => 6379)
     @value = Redis::Value.new('myvalue')
 
-Or can pass the handle into the new method:
-    
+Or you can pass the Redis handle into the new method:
+
     redis  = Redis.new(:host => 'localhost', :port => 6379)
     @value = Redis::Value.new('myvalue', redis)
 
 === Counters
 
+Create a new counter. The +counter_name+ is the key stored in Redis.
+
     @counter = Redis::Counter.new('counter_name')
     @counter.increment
     @counter.decrement
@@ -109,13 +55,18 @@ See the section on "Atomicity" for cool uses of atomic counter blocks.
 
 === Lists
 
-These work just like Ruby arrays:
+Lists work just like Ruby arrays:
 
     @list = Redis::List.new('list_name')
     @list << 'a'
     @list << 'b'
     @list.include? 'c'   # false
     @list.values  # ['a','b']
+    @list << 'c'
+    @list.delete('c')
+    @list[0]
+    @list[0,1]
+    @list[0..1]
     @list.shift
     @list.pop
     @list.clear
@@ -128,7 +79,7 @@ Sets work like the Ruby {Set}[http://ruby-doc.org/core/classes/Set.html] class:
     @set = Redis::Set.new('set_name')
     @set << 'a'
     @set << 'b'
-    @set << 'a'
+    @set << 'a'  # dup ignored
     @set.member? 'c'   # false
     @set.members  # ['a','b']
     @set.each do |member|
@@ -137,16 +88,105 @@ Sets work like the Ruby {Set}[http://ruby-doc.org/core/classes/Set.html] class:
     @set.clear
     # etc
 
+You can perform Redis intersections/unions easily:
+
+    @set1 = Redis::Set.new('set1')
+    @set2 = Redis::Set.new('set2')
+    @set3 = Redis::Set.new('set3')
+    members = @set1 & @set2   # intersection
+    members = @set1 | @set2   # union
+    members = @set1 + @set2   # union
+    members = @set1.intersection(@set2, @set3)  # multiple
+    members = @set1.union(@set2, @set3)         # multiple
+
+Or store them in Redis:
+
+    @set1.interstore('intername', @set2, @set3)
+    members = @set1.redis.get('intername')
+    @set1.unionstore('unionname', @set2, @set3)
+    members = @set1.redis.get('unionname')
+
 === Values
 
+Simple values are easy as well:
+
     @value = Redis::Value.new('value_name')
     @value.value = 'a'
     @value.delete
 
+== Example 2: Class Usage
+
+This method of use makes it easy to integrate Redis types with an existing
+ActiveRecord model, DataMapper resource, or other class.  Redis::Objects
+will work with any class that provides an +id+ method that returns a unique
+value.  Redis::Objects will automatically create keys that are unique to
+each object.
+
+=== Initialization
+
+If on Rails, config/initializers/redis.rb is a good place for this:
+
+    require 'redis'
+    require 'redis/objects'
+    Redis::Objects.redis = Redis.new(:host => 127.0.0.1, :port => 6379)
+
+=== Model Class
+
+Include Redis::Objects in any type of class:
+
+    class Team < ActiveRecord::Base
+      include Redis::Objects
+      
+      counter :hits
+      counter :runs
+      counter :outs
+      counter :inning, :start => 1
+      list :on_base
+      set :outfielders
+      value :at_bat
+    end
+
+Familiar Ruby array operations Just Work (TM):
+
+    @team = Team.find_by_name('New York Yankees')
+    @team.on_base << 'player1'
+    @team.on_base << 'player2'
+    @team.on_base << 'player3'
+    @team.on_base    # ['player1', 'player2']
+    @team.on_base.pop
+    @team.on_base.shift
+    @team.on_base.length  # 1
+    @team.on_base.delete('player3')
+
+Sets work like the Ruby {Set}[http://ruby-doc.org/core/classes/Set.html] class:
+    
+    @team.outfielders << 'outfielder1' << 'outfielder1'
+    @team.outfielders << 'outfielder2'
+    @team.outfielders  # ['outfielder1', 'outfielder2']
+    @team.outfielders.each do |player|
+      puts player
+    end
+    player = @team.outfielders.detect{|of| of == 'outfielder2'}
+
+Note counters cannot be assigned to, only incremented/decremented:
+
+    @team.hits.increment  # or incr
+    @team.hits.decrement  # or decr
+    @team.hits.incr(3)    # add 3
+    @team.runs = 4        # exception
+
+For free, you get a +redis+ handle usable in your class:
+
+    @team.redis.get('somekey')
+    @team.redis.smembers('someset')
+
+You can call any operation supported by {Redis}[http://code.google.com/p/redis/wiki/CommandReference]
+
 == Atomicity
 
 You are probably not handling atomicity correctly in your app.  For a fun rant
-on the topic, see {ATOMICITY}[ATOMICITY.doc]
+on the topic, see
+{ATOMICITY}[http://github.com/nateware/redis-objects/blob/master/ATOMICITY.rdoc].
 
 Atomic counters are a good way to handle concurrency:
 

data/lib/redis/set.rb

@@ -7,6 +7,8 @@ class Redis
     include Enumerable
 
     attr_reader :key, :options, :redis
+    
+    # Create a new Set.
     def initialize(key, redis=$redis, options={})
       @key = key
       @redis = redis
@@ -54,6 +56,53 @@ class Redis
       members.each(&block)
     end
 
+    # Return the intersection with another set.  Can pass it either another set
+    # object or set name.  Also available as & which is a bit cleaner:
+    #
+    #    members_in_both = set1 & set2
+    #
+    # If you want to specify multiple sets, you must use +intersection+:
+    #
+    #    members_in_all = set1.intersection(set2, set3, set4)
+    #    members_in_all = set1.inter(set2, set3, set4)  # alias
+    #
+    # Redis: SINTER
+    def intersection(*sets)
+      redis.sinter(key, *keys_from_objects(sets))
+    end
+    alias_method :intersect, :intersection
+    alias_method :inter, :intersection
+    alias_method :&, :intersection
+    
+    # Calculate the intersection and store it in Redis as +name+. Returns the number
+    # of elements in the stored intersection. Redis: SUNIONSTORE
+    def interstore(name, *sets)
+      redis.sinterstore(name, key, *keys_from_objects(sets))
+    end
+
+    # Return the union with another set.  Can pass it either another set
+    # object or set name. Also available as | and + which are a bit cleaner:
+    #
+    #    members_in_either = set1 | set2
+    #    members_in_either = set1 + set2
+    #
+    # If you want to specify multiple sets, you must use +union+:
+    #
+    #    members_in_all = set1.union(set2, set3, set4)
+    #
+    # Redis: SUNION
+    def union(*sets)
+      redis.sunion(key, *keys_from_objects(sets))
+    end
+    alias_method :|, :union
+    alias_method :+, :union
+
+    # Calculate the union and store it in Redis as +name+. Returns the number
+    # of elements in the stored union. Redis: SINTERSTORE
+    def unionstore(name, *sets)
+      redis.sunionstore(name, key, *keys_from_objects(sets))
+    end
+
     # The number of members in the set. Aliased as size. Redis: SCARD
     def length
       redis.scard(key)
@@ -72,5 +121,13 @@ class Redis
     def to_s
       members.join(', ')
     end
+    
+    private
+    
+    def keys_from_objects(sets)
+      raise ArgumentError, "Must pass in one or more set names" if sets.empty?
+      sets.collect{|set| set.is_a?(Redis::Set) ? set.key : set}
+    end
+    
   end
 end

data/spec/redis_objects_instance_spec.rb

@@ -0,0 +1,18 @@
+
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Redis::List do
+
+
+end
+
+describe Redis::Set do
+
+
+end
+
+describe Redis::Value do
+
+
+end
+

data/spec/redis_objects_model_spec.rb

@@ -1,6 +1,9 @@
 
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
+UNIONSTORE_KEY = 'test:unionstore'
+INTERSTORE_KEY = 'test:interstore'
+
 class Roster
   include Redis::Objects
   counter :available_slots, :start => 10
@@ -21,6 +24,10 @@ describe Redis::Objects do
   before :all do
     @roster  = Roster.new
     @roster2 = Roster.new
+    
+    @roster_1 = Roster.new(1)
+    @roster_2 = Roster.new(2)
+    @roster_3 = Roster.new(3)
   end
   
   before :each do
@@ -31,6 +38,11 @@ describe Redis::Objects do
     @roster.starting_pitcher.delete
     @roster.player_stats.clear
     @roster.outfielders.clear
+    @roster_1.outfielders.clear
+    @roster_2.outfielders.clear
+    @roster_3.outfielders.clear
+    @roster.redis.del(UNIONSTORE_KEY)
+    @roster.redis.del(INTERSTORE_KEY)
   end
 
   it "should provide a connection method" do
@@ -361,6 +373,33 @@ describe Redis::Objects do
     coll.should == ['c']
     @roster.outfielders.sort.should == ['a','b','c']
   end
+  
+  it "should handle set intersections and unions" do
+    @roster_1.outfielders << 'a' << 'b' << 'c' << 'd' << 'e'
+    @roster_2.outfielders << 'c' << 'd' << 'e' << 'f' << 'g'
+    @roster_3.outfielders << 'a' << 'd' << 'g' << 'l' << 'm'
+    @roster_1.outfielders.sort.should == %w(a b c d e)
+    @roster_2.outfielders.sort.should == %w(c d e f g)
+    @roster_3.outfielders.sort.should == %w(a d g l m)
+    (@roster_1.outfielders & @roster_2.outfielders).sort.should == ['c','d','e']
+    @roster_1.outfielders.intersection(@roster_2.outfielders).sort.should == ['c','d','e']
+    @roster_1.outfielders.intersection(@roster_2.outfielders, @roster_3.outfielders).sort.should == ['d']
+    @roster_1.outfielders.intersect(@roster_2.outfielders).sort.should == ['c','d','e']
+    @roster_1.outfielders.inter(@roster_2.outfielders, @roster_3.outfielders).sort.should == ['d']
+    @roster_1.outfielders.interstore(INTERSTORE_KEY, @roster_2.outfielders).should == 3
+    @roster_1.redis.smembers(INTERSTORE_KEY).sort.should == ['c','d','e']
+    @roster_1.outfielders.interstore(INTERSTORE_KEY, @roster_2.outfielders, @roster_3.outfielders).should == 1
+    @roster_1.redis.smembers(INTERSTORE_KEY).sort.should == ['d']
+
+    (@roster_1.outfielders | @roster_2.outfielders).sort.should == ['a','b','c','d','e','f','g']
+    (@roster_1.outfielders + @roster_2.outfielders).sort.should == ['a','b','c','d','e','f','g']
+    @roster_1.outfielders.union(@roster_2.outfielders).sort.should == ['a','b','c','d','e','f','g']
+    @roster_1.outfielders.union(@roster_2.outfielders, @roster_3.outfielders).sort.should == ['a','b','c','d','e','f','g','l','m']
+    @roster_1.outfielders.unionstore(UNIONSTORE_KEY, @roster_2.outfielders).should == 7
+    @roster_1.redis.smembers(UNIONSTORE_KEY).sort.should == ['a','b','c','d','e','f','g']
+    @roster_1.outfielders.unionstore(UNIONSTORE_KEY, @roster_2.outfielders, @roster_3.outfielders).should == 9
+    @roster_1.redis.smembers(UNIONSTORE_KEY).sort.should == ['a','b','c','d','e','f','g','l','m']
+  end
 
   it "should provide a lock method that accepts a block" do
     @roster.resort_lock.key.should == 'roster:1:resort_lock'
@@ -371,7 +410,7 @@ describe Redis::Objects do
     a.should be_true
   end
   
-  xit "should raise an exception if the timeout is exceeded" do
+  it "should raise an exception if the timeout is exceeded" do
     @roster.redis.set(@roster.resort_lock.key, 1)
     error = nil
     begin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: redis-objects
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Nate Wiger
@@ -11,8 +11,17 @@ cert_chain: []
 
 date: 2009-11-26 00:00:00 -08:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.1"
+    version: 
 description: Map Redis types directly to Ruby objects. Works with any class or ORM.
 email: nate@wiger.org
 executables: []
@@ -36,6 +45,7 @@ files:
 - lib/redis/objects.rb
 - lib/redis/set.rb
 - lib/redis/value.rb
+- spec/redis_objects_instance_spec.rb
 - spec/redis_objects_model_spec.rb
 - spec/spec_helper.rb
 - ATOMICITY.rdoc
@@ -62,8 +72,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version 
       version: "0"
   version: 
-requirements: []
-
+requirements: 
+- redis, v0.1 or greater
 rubyforge_project: redis-objects
 rubygems_version: 1.3.5
 signing_key: