redis-objects 0.2.3 → 0.2.4

data/README.rdoc

@@ -1,26 +1,31 @@
 = Redis::Objects - Map Redis types directly to Ruby objects
 
-This is *not* an ORM.  People that are wrapping ORM's around Redis are missing
-the point.
+This is *not* an ORM. People that are wrapping ORM’s around Redis are missing 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.  This gem maps {Redis types}[http://code.google.com/p/redis/wiki/CommandReference]
-to Ruby objects, via a thin layer over Ezra's +redis+ gem.
+The killer feature of Redis is that it allows you to perform _atomic_ operations
+on _individual_ data structures, like counters, lists, and sets.  The *atomic* part is HUGE.
+Using an ORM wrapper that retrieves a "record", updates values, then sends those values back,
+_removes_ the atomicity, cutting the nuts off the major advantage of Redis.  Just use MySQL, k?
+
+This gem provides a Rubyish interface to Redis, by mapping {Redis types}[http://code.google.com/p/redis/wiki/CommandReference]
+to Ruby objects, via a thin layer over Ezra's +redis+ gem.  It offers several advantages
+over the lower-level redis-rb API:
+
+1. Easy to integrate directly with existing ORMs - ActiveRecord, DataMapper, etc.  Add counters to your model!
+2. Complex data structures are automatically Marshaled
+3. Integers are returned as integers, rather than '17'
+4. Higher-level types are provided, such as Locks, that wrap multiple calls
 
 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],
+for a fun rant on the topic, see {An Atomic Rant}[http://nateware.com/2010/02/18/an-atomic-rant],
 or scroll down to "Atomicity" in this README.
 
-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.
+There are two ways to use Redis::Objects, either as an include in a model class (to
+integrate with ORMs or other classes), 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: Model Class Usage
@@ -29,27 +34,30 @@ Using Redis::Objects this way makes it trivial 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.
+each object, in the format:
+
+    model_name:id:field_name
 
 === Initialization
 
-Redis::Objects needs a handle created by Redis.new.  If you're on Rails,
-config/initializers/redis.rb is a good place for this:
+Redis::Objects needs a handle created by Redis.new.  (If you're 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)
 
-You can use Redis::Objects with any framework.  There are *no* dependencies on Rails.
-I use it from Sinatra and rake tasks all the time.
+Remember you can use Redis::Objects in any Ruby code.  There are *no* dependencies
+on Rails.  Standalone, Sinatra, Resque - no problem.
 
 === Model Class
 
-Include Redis::Objects in any type of class:
+You can include Redis::Objects in any type of class:
 
     class Team < ActiveRecord::Base
       include Redis::Objects
 
+      lock :trade_players, :expiration => 15  # sec
       counter :hits
       counter :runs
       counter :outs
@@ -82,7 +90,7 @@ Sets work too:
     end
     player = @team.outfielders.detect{|of| of == 'outfielder2'}
 
-And you can do intersections between ORM objects (kinda cool):
+And you can do intersections between objects (kinda cool):
 
     @team1.outfielders | @team2.outfielders   # outfielders on both teams
     @team1.outfielders & @team2.outfielders   # in baseball, should be empty :-)
@@ -101,26 +109,28 @@ Finally, for free, you get a +redis+ method that points directly to a Redis conn
     @team.redis.get('somekey')
     @team.redis.smembers('someset')
 
-You can use the +redis+ handle to directly call any {Redis command}[http://code.google.com/p/redis/wiki/CommandReference]
+You can use the +redis+ handle to directly call any {Redis API command}[http://code.google.com/p/redis/wiki/CommandReference].
 
 == Example 2: Standalone Usage
 
-There is a Ruby object that maps to each Redis type.
+There is a Ruby class that maps to each Redis type, with methods for each
+{Redis API command}[http://code.google.com/p/redis/wiki/CommandReference].
+Note that calling +new+ does not imply it's actually a "new" value - it just
+creates a mapping between that object and the corresponding Redis data structure,
+which may already exist on the redis-server.
 
 === Initialization
 
-Again, Redis::Objects needs a handle to the +redis+ server.  For standalone use, you
+Redis::Objects needs a handle to the +redis+ server.  For standalone use, you
 can either set the $redis global variable:
 
     $redis = Redis.new(:host => 'localhost', :port => 6379)
-    @value = Redis::Value.new('myvalue')
+    @list  = Redis::List.new('mylist')
 
 Or you can pass the Redis handle into the new method for each type:
 
     redis  = Redis.new(:host => 'localhost', :port => 6379)
-    @value = Redis::Value.new('myvalue', redis)
-
-Your choice.
+    @list  = Redis::List.new('mylist', redis)
 
 === Counters
 
@@ -140,6 +150,34 @@ This gem provides a clean way to do atomic blocks as well:
 
 See the section on "Atomicity" for cool uses of atomic counter blocks.
 
+=== Locks
+
+A convenience class that wraps the pattern of {using +setnx+ to perform locking}[http://code.google.com/p/redis/wiki/SetnxCommand].
+
+    require 'redis/lock'
+    @lock = Redis::Lock.new('image_resizing', :expiration => 15, :timeout => 0.1)
+    @lock.lock do
+      # do work
+    end
+
+This can be especially useful if you're running batch jobs spread across multiple hosts.
+
+=== Values
+
+Simple values are easy as well:
+
+    require 'redis/value'
+    @value = Redis::Value.new('value_name')
+    @value.value = 'a'
+    @value.delete
+
+Of course complex data is no problem:
+
+    @account = Account.create!(params[:account])
+    @newest  = Redis::Value.new('newest_account')
+    @newest.value = @account.attributes
+    puts @newest.value['username']
+
 === Lists
 
 Lists work just like Ruby arrays:
@@ -167,6 +205,8 @@ Complex data types are no problem:
     @list.each do |el|
       puts "#{el[:name]} lives in #{el[:city]}"
     end
+    
+This gem will automatically marshal complex data, similar to how session stores work.
 
 === Sets
 
@@ -219,26 +259,40 @@ And use complex data types too:
     @set1 - @set2  # Peter
     @set1 | @set2  # all 3 people
 
-=== Values
+=== Sorted Sets
 
-Simple values are easy as well:
+Due to their unique properties, Sorted Sets work like a hybrid between
+a Hash and an Array.  You assign like a Hash, but retrieve like an Array:
 
-    require 'redis/value'
-    @value = Redis::Value.new('value_name')
-    @value.value = 'a'
-    @value.delete
+    require 'redis/sorted_set'
+    @sorted_set = Redis::SortedSet.new('number_of_posts')
+    @sorted_set['Nate']  = 15
+    @sorted_set['Peter'] = 75
+    @sorted_set['Jeff']  = 24
+    
+    # atomic increment
+    @sorted_set.increment('Nate')
+    @sorted_set.incr('Peter')   # shorthand
+    @sorted_set.incr('Jeff', 4)
 
-Of course complex data is no problem:
+    @sorted_set[0,2]            # => ["Nate", "Jeff", "Peter"]
+    @sorted_set.first           # => "Nate"
+    @sorted_set.last            # => "Nate"
+    @sorted_set.revrange(0,2)   # => ["Peter", "Jeff", "Nate"]
 
-    @account = Account.create!(params[:account])
-    @newest  = Redis::Value.new('newest_account')
-    @newest.value = @account
+    @sorted_set['Newbie'] = 1
+    @sorted_set.members         # => ["Newbie", "Nate", "Jeff", "Peter"]
+
+    @sorted_set.rangebyscore(10, 100, :limit => 2)   # => ["Nate", "Jeff"]
+    @sorted_set.members(:withscores => true)         # => [["Newbie", 1], ["Nate", 16], ["Jeff", 28], ["Peter", 76]]
+
+The other Redis Sorted Set commands are supported as well; see {SortedSets API}[http://code.google.com/p/redis/wiki/SortedSets].
 
 == Atomic Counters and Locks
 
 You are probably not handling atomicity correctly in your app.  For a fun rant
 on the topic, see
-{ATOMICITY}[http://github.com/nateware/redis-objects/blob/master/ATOMICITY.rdoc].
+{An Atomic Rant}[http://nateware.com/2010/02/18/an-atomic-rant].
 
 Atomic counters are a good way to handle concurrency:
 

data/lib/redis/counter.rb

@@ -11,10 +11,10 @@ class Redis
     include Redis::Helpers::CoreCommands
 
     attr_reader :key, :options, :redis
-    def initialize(key, redis=$redis, options={})
+    def initialize(key, *args)
       @key = key
-      @redis = redis
-      @options = options
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @redis = args.first || $redis
       @options[:start] ||= 0
       @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
     end
@@ -25,6 +25,7 @@ class Redis
     # disconnecting all players).
     def reset(to=options[:start])
       redis.set key, to.to_i
+      true  # hack for redis-rb regression
     end
 
     # Returns the current value of the counter.  Normally just calling the
@@ -42,7 +43,7 @@ class Redis
     # counter will automatically be decremented to its previous value.  This
     # method is aliased as incr() for brevity.
     def increment(by=1, &block)
-      val = redis.incr(key, by).to_i
+      val = redis.incrby(key, by).to_i
       block_given? ? rewindable_block(:decrement, val, &block) : val
     end
     alias_method :incr, :increment
@@ -53,7 +54,7 @@ class Redis
     # counter will automatically be incremented to its previous value.  This
     # method is aliased as incr() for brevity.
     def decrement(by=1, &block)
-      val = redis.decr(key, by).to_i
+      val = redis.decrby(key, by).to_i
       block_given? ? rewindable_block(:increment, val, &block) : val
     end
     alias_method :decr, :decrement

data/lib/redis/helpers/core_commands.rb

@@ -15,7 +15,7 @@ class Redis
       def type
         redis.type key
       end
-      
+
       def rename(name, setkey=true)
         dest = name.is_a?(self.class) ? name.key : name
         ret  = redis.rename key, dest
@@ -41,6 +41,14 @@ class Redis
       def move(dbindex)
         redis.move key, dbindex
       end
+      
+      # See the documentation for SORT: http://code.google.com/p/redis/wiki/SortCommand
+      # TODO
+      # def sort(options)
+      #   args = []
+      #   args += ['sort']
+      #   from_redis redis.sort key
+      # end
     end
   end
 end

data/lib/redis/list.rb

@@ -12,10 +12,10 @@ class Redis
     include Redis::Helpers::Serialize
 
     attr_reader :key, :options, :redis
-    def initialize(key, redis=$redis, options={})
+    def initialize(key, *args)
       @key = key
-      @redis = redis
-      @options = options
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @redis = args.first || $redis
     end
     
     # Works like push.  Can chain together: list << 'a' << 'b'

data/lib/redis/lock.rb

@@ -10,11 +10,12 @@ class Redis
     class LockTimeout < StandardError; end #:nodoc:
 
     attr_reader :key, :options, :redis
-    def initialize(key, redis=$redis, options={})
+    def initialize(key, *args)
       @key = key
-      @redis = redis
-      @options = options
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @redis = args.first || $redis
       @options[:timeout] ||= 5
+      @options[:init] = false if @options[:init].nil? # default :init to false
       @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
     end
 

data/lib/redis/objects.rb

@@ -6,7 +6,7 @@ class Redis
   # Redis::Objects enables high-performance atomic operations in your app
   # by leveraging the atomic features of the Redis server.  To use Redis::Objects,
   # first include it in any class you want.  (This example uses an ActiveRecord
-  # subclass, but that is *not* required.) Then, use +counter+ and +lock+
+  # subclass, but that is *not* required.) Then, use +counter+, +lock+, +set+, etc
   # to define your primitives:
   #
   #   class Game < ActiveRecord::Base
@@ -14,8 +14,8 @@ class Redis
   #
   #     counter :joined_players
   #     counter :active_players
-  #     set :player_ids
   #     lock :archive_game
+  #     set :player_ids
   #   end
   # 
   # The, you can use these counters both for bookeeping and as atomic actions:
@@ -39,10 +39,11 @@ class Redis
     dir = File.expand_path(__FILE__.sub(/\.rb$/,''))
 
     autoload :Counters, File.join(dir, 'counters')
-    autoload :Values, File.join(dir, 'values')
     autoload :Lists, File.join(dir, 'lists')
-    autoload :Sets, File.join(dir, 'sets')
     autoload :Locks, File.join(dir, 'locks')
+    autoload :Sets, File.join(dir, 'sets')
+    autoload :SortedSets, File.join(dir, 'sorted_sets')
+    autoload :Values, File.join(dir, 'values')
 
     class NotConnected  < StandardError; end
 
@@ -61,10 +62,11 @@ class Redis
         
         # Pull in each object type
         klass.send :include, Redis::Objects::Counters
-        klass.send :include, Redis::Objects::Values
         klass.send :include, Redis::Objects::Lists
-        klass.send :include, Redis::Objects::Sets
         klass.send :include, Redis::Objects::Locks
+        klass.send :include, Redis::Objects::Sets
+        klass.send :include, Redis::Objects::SortedSets
+        klass.send :include, Redis::Objects::Values
       end
     end
 

data/lib/redis/objects/counters.rb

@@ -56,7 +56,7 @@ class Redis
         def increment_counter(name, id=nil, by=1, &block)
           verify_counter_defined!(name, id)
           initialize_counter!(name, id)
-          value = redis.incr(field_key(name, id), by).to_i
+          value = redis.incrby(field_key(name, id), by).to_i
           block_given? ? rewindable_block(:decrement_counter, name, id, value, &block) : value
         end
 
@@ -65,7 +65,7 @@ class Redis
         def decrement_counter(name, id=nil, by=1, &block)
           verify_counter_defined!(name, id)
           initialize_counter!(name, id)
-          value = redis.decr(field_key(name, id), by).to_i
+          value = redis.decrby(field_key(name, id), by).to_i
           block_given? ? rewindable_block(:increment_counter, name, id, value, &block) : value
         end
 
@@ -73,7 +73,8 @@ class Redis
         def reset_counter(name, id=nil, to=nil)
           verify_counter_defined!(name, id)
           to = @redis_objects[name][:start] if to.nil?
-          redis.set(field_key(name, id), to)
+          redis.set(field_key(name, id), to.to_i)
+          true
         end
         
         private

data/lib/redis/objects/locks.rb

@@ -16,7 +16,6 @@ class Redis
         # so it can be used alongside ActiveRecord/DataMapper, etc.
         def lock(name, options={})
           options[:timeout] ||= 5  # seconds
-          options[:init] = false if options[:init].nil? # default :init to false
           @redis_objects[name] = options.merge(:type => :lock)
           if options[:global]
             instance_eval <<-EndMethods
@@ -36,9 +35,6 @@ class Redis
               end
             EndMethods
           end
-
-          
-          
         end
 
         # Obtain a lock, and execute the block synchronously.  Any other code

data/lib/redis/objects/sorted_sets.rb

@@ -0,0 +1,45 @@
+# This is the class loader, for use as "include Redis::Objects::Sets"
+# For the object itself, see "Redis::Set"
+require 'redis/sorted_set'
+class Redis
+  module Objects
+    module SortedSets
+      def self.included(klass)
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+      end
+
+      # Class methods that appear in your class when you include Redis::Objects.
+      module ClassMethods
+        # Define a new list.  It will function like a regular instance
+        # method, so it can be used alongside ActiveRecord, DataMapper, etc.
+        def sorted_set(name, options={})
+          @redis_objects[name] = options.merge(:type => :sorted_set)
+          if options[:global]
+            instance_eval <<-EndMethods
+              def #{name}
+                @#{name} ||= Redis::SortedSet.new(field_key(:#{name}, ''), redis, @redis_objects[:#{name}])
+              end
+            EndMethods
+            class_eval <<-EndMethods
+              def #{name}
+                self.class.#{name}
+              end
+            EndMethods
+          else
+            class_eval <<-EndMethods
+              def #{name}
+                @#{name} ||= Redis::SortedSet.new(field_key(:#{name}), redis, self.class.redis_objects[:#{name}])
+              end
+            EndMethods
+          end
+          
+        end
+      end
+
+      # Instance methods that appear in your class when you include Redis::Objects.
+      module InstanceMethods
+      end
+    end
+  end
+end

data/lib/redis/set.rb

@@ -13,10 +13,10 @@ class Redis
     attr_reader :key, :options, :redis
     
     # Create a new Set.
-    def initialize(key, redis=$redis, options={})
+    def initialize(key, *args)
       @key = key
-      @redis = redis
-      @options = options
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @redis = args.first || $redis
     end
 
     # Works like add.  Can chain together: list << 'a' << 'b'

data/lib/redis/sorted_set.rb

@@ -0,0 +1,275 @@
+class Redis
+  #
+  # Class representing a sorted set.
+  #
+  class SortedSet
+    # require 'enumerator'
+    # include Enumerable
+    require 'redis/helpers/core_commands'
+    include Redis::Helpers::CoreCommands
+    require 'redis/helpers/serialize'
+    include Redis::Helpers::Serialize
+
+    attr_reader :key, :options, :redis
+    
+    # Create a new SortedSet.
+    def initialize(key, *args)
+      @key = key
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @redis = args.first || $redis
+    end
+
+    # How to add values using a sorted set.  The key is the member, eg,
+    # "Peter", and the value is the score, eg, 163.  So:
+    #    num_posts['Peter'] = 163 
+    def []=(member, score)
+      add(member, score)
+    end
+
+    # Add a member and its corresponding value to Redis.  Note that the
+    # arguments to this are flipped; the member comes first rather than
+    # the score, since the member is the unique item (not the score).
+    def add(member, score)
+      redis.zadd(key, score, to_redis(member))
+    end
+
+    # Same functionality as Ruby arrays.  If a single number is given, return
+    # just the element at that index using Redis: ZRANGE. Otherwise, return
+    # a range of values using Redis: ZRANGE.
+    def [](index, length=nil)
+      if index.is_a? Range
+        range(index.first, index.last)
+      elsif length
+        range(index, length)
+      else
+        at(index)
+      end
+    end
+
+    # Return the score of the specified element of the sorted set at key. If the
+    # specified element does not exist in the sorted set, or the key does not exist
+    # at all, nil is returned. Redis: ZSCORE.
+    def score(member)
+      redis.zscore(key, to_redis(member)).to_i
+    end
+
+    # Return the rank of the member in the sorted set, with scores ordered from
+    # low to high. +revrank+ returns the rank with scores ordered from high to low.
+    # When the given member does not exist in the sorted set, nil is returned.
+    # The returned rank (or index) of the member is 0-based for both commands
+    def rank(member)
+      redis.zrank(key, to_redis(member)).to_i
+    end
+
+    def revrank(member)
+      redis.zrevrank(key, to_redis(member)).to_i
+    end
+
+    # Return all members of the sorted set with their scores.  Extremely CPU-intensive.
+    # Better to use a range instead.
+    def members(options={})
+      range(0, -1, options)
+    end
+
+    # Return a range of values from +start_index+ to +end_index+.  Can also use
+    # the familiar list[start,end] Ruby syntax. Redis: ZRANGE
+    def range(start_index, end_index, options={})
+      if options[:withscores]
+        val = from_redis redis.zrange(key, start_index, end_index, 'withscores')
+        ret = []
+        while k = val.shift and v = val.shift
+          ret << [k, v.to_i]
+        end
+        ret
+      else
+        from_redis redis.zrange(key, start_index, end_index)
+      end
+    end
+
+    # Return a range of values from +start_index+ to +end_index+ in reverse order. Redis: ZREVRANGE
+    def revrange(start_index, end_index, options={})
+      if options[:withscores]
+        val = from_redis redis.zrevrange(key, start_index, end_index, 'withscores')
+        ret = []
+        while k = val.shift and v = val.shift
+          ret << [k, v.to_i]
+        end
+        ret
+      else
+        from_redis redis.zrevrange(key, start_index, end_index)
+      end
+    end
+
+    # Return the all the elements in the sorted set at key with a score between min and max
+    # (including elements with score equal to min or max).  Options:
+    #     :count, :offset - passed to LIMIT
+    #     :withscores     - if true, scores are returned as well
+    # Redis: ZRANGEBYSCORE
+    def rangebyscore(min, max, options={})
+      args = []
+      args += ['limit', options[:offset] || 0, options[:limit] || options[:count]] if
+                options[:offset] || options[:limit] || options[:count]
+      args += ['withscores'] if options[:withscores]
+      from_redis redis.zrangebyscore(key, min, max, *args)
+    end
+
+    # Forwards compat (not yet implemented in Redis)
+    def revrangebyscore(min, max, options={})
+      args = []
+      args += ['limit', options[:offset] || 0, options[:limit] || options[:count]] if
+                options[:offset] || options[:limit] || options[:count]
+      args += ['withscores'] if options[:withscores]
+      from_redis redis.zrevrangebyscore(key, min, max, *args)
+    end
+
+    # Remove all elements in the sorted set at key with rank between start and end. Start and end are
+    # 0-based with rank 0 being the element with the lowest score. Both start and end can be negative
+    # numbers, where they indicate offsets starting at the element with the highest rank. For example:
+    # -1 is the element with the highest score, -2 the element with the second highest score and so forth. 
+    # Redis: ZREMRANGEBYRANK
+    def remrangebyrank(min, max)
+      redis.zremrangebyrank(key, min, max)
+    end
+
+    # Remove all the elements in the sorted set at key with a score between min and max (including
+    # elements with score equal to min or max). Redis: ZREMRANGEBYSCORE
+    def remrangebyscore(min, max)
+      redis.zremrangebyscore(key, min, max)
+    end
+
+    # Delete the value from the set.  Redis: ZREM
+    def delete(value)
+      redis.zrem(key, value)
+    end
+
+    # Increment the rank of that member atomically and return the new value. This
+    # method is aliased as incr() for brevity. Redis: ZINCRBY
+    def increment(member, by=1)
+      redis.zincrby(key, by, member).to_i
+    end
+    alias_method :incr, :increment
+    alias_method :incrby, :increment
+
+    # Convenience to calling increment() with a negative number. 
+    def decrement(by=1)
+      redis.zincrby(key, -by).to_i
+    end
+    alias_method :decr, :decrement
+    alias_method :decrby, :decrement
+
+    # 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)
+      from_redis redis.zinter(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.zinterstore(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)
+      from_redis redis.zunion(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: SUNIONSTORE
+    def unionstore(name, *sets)
+      redis.zunionstore(name, key, *keys_from_objects(sets))
+    end
+
+    # Return the difference vs another set.  Can pass it either another set
+    # object or set name. Also available as ^ or - which is a bit cleaner:
+    #
+    #    members_difference = set1 ^ set2
+    #    members_difference = set1 - set2
+    #
+    # If you want to specify multiple sets, you must use +difference+:
+    #
+    #    members_difference = set1.difference(set2, set3, set4)
+    #    members_difference = set1.diff(set2, set3, set4)
+    #
+    # Redis: SDIFF
+    def difference(*sets)
+      from_redis redis.zdiff(key, *keys_from_objects(sets))
+    end
+    alias_method :diff, :difference
+    alias_method :^, :difference
+    alias_method :-, :difference
+
+    # Calculate the diff and store it in Redis as +name+. Returns the number
+    # of elements in the stored union. Redis: SDIFFSTORE
+    def diffstore(name, *sets)
+      redis.zdiffstore(name, key, *keys_from_objects(sets))
+    end
+
+    # Returns true if the set has no members. Redis: SCARD == 0
+    def empty?
+      length == 0
+    end
+
+    def ==(x)
+      members == x
+    end
+    
+    def to_s
+      members.join(', ')
+    end
+
+    # Return the value at the given index. Can also use familiar list[index] syntax.
+    # Redis: ZRANGE
+    def at(index)
+      range(index, index).first
+    end
+
+    # Return the first element in the list. Redis: ZRANGE(0)
+    def first
+      at(0)
+    end
+
+    # Return the last element in the list. Redis: ZRANGE(-1)
+    def last
+      at(-1)
+    end
+    
+    # The number of members in the set. Aliased as size. Redis: ZCARD
+    def length
+      redis.zcard(key)
+    end
+    alias_method :size, :length
+
+    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::SortedSet) ? set.key : set}
+    end
+    
+  end
+end

data/lib/redis/value.rb

@@ -9,10 +9,10 @@ class Redis
     include Redis::Helpers::Serialize
 
     attr_reader :key, :options, :redis
-    def initialize(key, redis=$redis, options={})
+    def initialize(key, *args)
       @key = key
-      @redis = redis
-      @options = options
+      @options = args.last.is_a?(Hash) ? args.pop : {}
+      @redis = args.first || $redis
       @redis.setnx(key, @options[:default]) if @options[:default]
     end
 

data/spec/redis_objects_instance_spec.rb

@@ -3,9 +3,10 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 require 'redis/counter'
 require 'redis/list'
-require 'redis/set'
 require 'redis/value'
 require 'redis/lock'
+require 'redis/set'
+require 'redis/sorted_set'
 
 describe Redis::Value do
   before :all do
@@ -47,6 +48,7 @@ describe Redis::Value do
     old.should be_nil
     old.value = 'Tuff'
     @value.renamenx('spec/value').should be_false
+    @value.value.should == 'Peter Pan'
   end
 
   after :all do
@@ -160,9 +162,11 @@ describe Redis::List do
     old = Redis::List.new('spec/list')
     old.should be_empty
     old << 'Tuff'
+    old.values.should == ['Tuff']
     @list.renamenx('spec/list').should be_false
     @list.renamenx(old).should be_false
     @list.renamenx('spec/foo').should be_true
+    old.values.should == ['Tuff']
     @list.clear
     @list.redis.del('spec/list2')
   end
@@ -172,6 +176,134 @@ describe Redis::List do
   end
 end
 
+describe Redis::Counter do
+  before :all do
+    @counter  = Redis::Counter.new('spec/counter')
+    @counter2 = Redis::Counter.new('spec/counter')
+  end
+
+  before :each do
+    @counter.reset
+  end
+
+  it "should support increment/decrement of counters" do
+    @counter.key.should == 'spec/counter'
+    @counter.incr(10)
+    @counter.should == 10
+    
+    # math proxy ops
+    (@counter == 10).should be_true
+    (@counter <= 10).should be_true
+    (@counter < 11).should be_true
+    (@counter > 9).should be_true
+    (@counter >= 10).should be_true
+    "#{@counter}".should == "10"
+
+    @counter.increment.should == 11
+    @counter.increment.should == 12
+    @counter2.increment.should == 13
+    @counter2.increment(2).should == 15
+    @counter.decrement.should == 14
+    @counter2.decrement.should == 13
+    @counter.decrement.should == 12
+    @counter2.decrement(4).should == 8
+    @counter.should == 8
+    @counter.reset.should be_true
+    @counter.should == 0
+    @counter.reset(15).should be_true
+    @counter.should == 15
+  end
+
+  after :all do
+    @counter.delete
+  end
+end
+
+describe Redis::Lock do
+  before :each do
+    $redis.flushall
+  end
+
+  it "should set the value to the expiration" do
+    start = Time.now
+    expiry = 15
+    lock = Redis::Lock.new(:test_lock, :expiration => expiry)
+    lock.lock do
+      expiration = $redis.get("test_lock").to_f
+
+      # The expiration stored in redis should be 15 seconds from when we started
+      # or a little more
+      expiration.should be_close((start + expiry).to_f, 2.0)
+    end
+
+    # key should have been cleaned up
+    $redis.get("test_lock").should be_nil
+  end
+
+  it "should set value to 1 when no expiration is set" do
+    lock = Redis::Lock.new(:test_lock)
+    lock.lock do
+      $redis.get('test_lock').should == '1'
+    end
+
+    # key should have been cleaned up
+    $redis.get("test_lock").should be_nil
+  end
+
+  it "should let lock be gettable when lock is expired" do
+    expiry = 15
+    lock = Redis::Lock.new(:test_lock, :expiration => expiry, :timeout => 0.1)
+
+    # create a fake lock in the past
+    $redis.set("test_lock", Time.now-(expiry + 60))
+
+    gotit = false
+    lock.lock do
+      gotit = true
+    end
+
+    # should get the lock because it has expired
+    gotit.should be_true
+    $redis.get("test_lock").should be_nil
+  end
+
+  it "should not let non-expired locks be gettable" do
+    expiry = 15
+    lock = Redis::Lock.new(:test_lock, :expiration => expiry, :timeout => 0.1)
+
+    # create a fake lock
+    $redis.set("test_lock", (Time.now + expiry).to_f)
+
+    gotit = false
+    error = nil
+    begin
+      lock.lock do
+        gotit = true
+      end
+    rescue => error
+    end
+
+    error.should be_kind_of(Redis::Lock::LockTimeout)
+
+    # should not have the lock
+    gotit.should_not be_true
+
+    # lock value should still be set
+    $redis.get("test_lock").should_not be_nil
+  end
+
+  it "should not remove the key if lock is held past expiration" do
+    lock = Redis::Lock.new(:test_lock, :expiration => 0.0)
+
+    lock.lock do
+      sleep 1.1
+    end
+
+    # lock value should still be set since the lock was held for more than the expiry
+    $redis.get("test_lock").should_not be_nil
+  end
+end
+
 describe Redis::Set do
   before :all do
     @set = Redis::Set.new('spec/set')
@@ -289,132 +421,157 @@ describe Redis::Set do
   end
 end
 
-describe Redis::Counter do
+describe Redis::SortedSet do
   before :all do
-    @counter  = Redis::Counter.new('spec/counter')
-    @counter2 = Redis::Counter.new('spec/counter')
+    @set = Redis::SortedSet.new('spec/zset')
+    @set_1 = Redis::SortedSet.new('spec/zset_1')
+    @set_2 = Redis::SortedSet.new('spec/zset_2')
+    @set_3 = Redis::SortedSet.new('spec/zset_3')
   end
 
   before :each do
-    @counter.reset
+    @set.clear
+    @set_1.clear
+    @set_2.clear
+    @set_3.clear
   end
 
-  it "should support increment/decrement of counters" do
-    @counter.key.should == 'spec/counter'
-    @counter.incr(10)
-    @counter.should == 10
+  it "should handle sets of simple values" do
+    @set.should be_empty
+    @set['a'] = 11
+    @set['a'] = 21
+    @set.add('a', 5)
+    @set.score('a').should == 5
+    @set['a'] = 3
+    @set['b'] = 5
+    @set['c'] = 4
+
+    @set[0,-1].should == ['a','c','b']
+    @set.range(0,-1).should == ['a','c','b']
+    @set.revrange(0,-1).should == ['b','c','a']
+    @set[0..1].should == ['a','c']
+    @set[1].should == 'c'
+    @set.at(1).should == 'c'
+    @set.first.should == 'a'
+    @set.last.should == 'b'
+
+    @set.members.should == ['a','c','b']
+    @set.members(:withscores => true).should == [['a',3],['c',4],['b',5]]
+
+    @set['b'] = 5
+    @set['b'] = 6
+    @set.score('b').should == 6
+    @set.delete('c')
+    @set.to_s.should == 'a, b'
+    @set.should == ['a','b']
+    @set.members.should == ['a','b']
+    @set['d'] = 0
     
-    # math proxy ops
-    (@counter == 10).should be_true
-    (@counter <= 10).should be_true
-    (@counter < 11).should be_true
-    (@counter > 9).should be_true
-    (@counter >= 10).should be_true
-    "#{@counter}".should == "10"
-
-    @counter.increment.should == 11
-    @counter.increment.should == 12
-    @counter2.increment.should == 13
-    @counter2.increment(2).should == 15
-    @counter.decrement.should == 14
-    @counter2.decrement.should == 13
-    @counter.decrement.should == 12
-    @counter2.decrement(4).should == 8
-    @counter.should == 8
-    @counter.reset.should be_true
-    @counter.should == 0
-    @counter.reset(15).should be_true
-    @counter.should == 15
-  end
-
-  after :all do
-    @counter.delete
-  end
-end
-
-describe Redis::Lock do
-
-  before :each do
-    $redis.flushall
-  end
-
-  it "should set the value to the expiration" do
-    start = Time.now
-    expiry = 15
-    lock = Redis::Lock.new(:test_lock, $redis, :expiration => expiry, :init => false)
-    lock.lock do
-      expiration = $redis.get("test_lock").to_f
-
-      # The expiration stored in redis should be 15 seconds from when we started
-      # or a little more
-      expiration.should be_close((start + expiry).to_f, 2.0)
-    end
-
-    # key should have been cleaned up
-    $redis.get("test_lock").should be_nil
+    @set.rangebyscore(0, 4).should == ['d','a']
+    @set.rangebyscore(0, 4, :count => 1).should == ['d']
+    @set.rangebyscore(0, 4, :count => 2).should == ['d','a']
+    @set.rangebyscore(0, 4, :limit => 2).should == ['d','a']
+
+    # Redis 1.3.5
+    # @set.rangebyscore(0,4, :withscores => true).should == [['d',4],['a',3]]
+    # @set.revrangebyscore(0,4).should == ['d','a']
+    # @set.revrangebyscore(0,4, :count => 2).should == ['a','d']
+    # @set.rank('b').should == 2
+    # @set.revrank('b').should == 3
+
+    @set['f'] = 100
+    @set['g'] = 110
+    @set['h'] = 120
+    @set['j'] = 130
+    @set.incr('h', 20)
+    @set.remrangebyscore(100, 120)
+    @set.members.should == ['d','a','b','j','h']
+
+    # Redis 1.3.5
+    # @set['h'] = 12
+    # @set['j'] = 13
+    # @set.remrangebyrank(4,-1)
+    # @set.members.should == ['d','a','b']
+
+    @set.delete('d')
+    @set['c'] = 200
+    @set.members.should == ['a','b','j','h','c']
+    @set.delete('c')
+    @set.length.should == 4
+    @set.size.should == 4
   end
 
-  it "should set value to 1 when no expiration is set" do
-    lock = Redis::Lock.new(:test_lock, $redis, :init => false)
-    lock.lock do
-      $redis.get('test_lock').should == '1'
-    end
+  # Not until Redis 1.3.5 with hashes
+  xit "Redis 1.3.5: should handle set intersections, unions, and diffs" do
+    @set_1['a'] = 5
+    @set_2['b'] = 18
+    @set_2['c'] = 12
 
-    # key should have been cleaned up
-    $redis.get("test_lock").should be_nil
-  end
+    @set_2['a'] = 10
+    @set_2['b'] = 15
+    @set_2['c'] = 15
 
-  it "should let lock be gettable when lock is expired" do
-    expiry = 15
-    lock = Redis::Lock.new(:test_lock, $redis, :expiration => expiry, :timeout => 0.1, :init => false)
+    (@set_1 & @set_2).sort.should == ['c','d','e']
 
-    # create a fake lock in the past
-    $redis.set("test_lock", Time.now-(expiry + 60))
+    @set_1 << 'a' << 'b' << 'c' << 'd' << 'e'
+    @set_2 << 'c' << 'd' << 'e' << 'f' << 'g'
+    @set_3 << 'a' << 'd' << 'g' << 'l' << 'm'
+    @set_1.sort.should == %w(a b c d e)
+    @set_2.sort.should == %w(c d e f g)
+    @set_3.sort.should == %w(a d g l m)
+    (@set_1 & @set_2).sort.should == ['c','d','e']
+    @set_1.intersection(@set_2).sort.should == ['c','d','e']
+    @set_1.intersection(@set_2, @set_3).sort.should == ['d']
+    @set_1.intersect(@set_2).sort.should == ['c','d','e']
+    @set_1.inter(@set_2, @set_3).sort.should == ['d']
+    @set_1.interstore(INTERSTORE_KEY, @set_2).should == 3
+    @set_1.redis.smembers(INTERSTORE_KEY).sort.should == ['c','d','e']
+    @set_1.interstore(INTERSTORE_KEY, @set_2, @set_3).should == 1
+    @set_1.redis.smembers(INTERSTORE_KEY).sort.should == ['d']
 
-    gotit = false
-    lock.lock do
-      gotit = true
-    end
+    (@set_1 | @set_2).sort.should == ['a','b','c','d','e','f','g']
+    (@set_1 + @set_2).sort.should == ['a','b','c','d','e','f','g']
+    @set_1.union(@set_2).sort.should == ['a','b','c','d','e','f','g']
+    @set_1.union(@set_2, @set_3).sort.should == ['a','b','c','d','e','f','g','l','m']
+    @set_1.unionstore(UNIONSTORE_KEY, @set_2).should == 7
+    @set_1.redis.smembers(UNIONSTORE_KEY).sort.should == ['a','b','c','d','e','f','g']
+    @set_1.unionstore(UNIONSTORE_KEY, @set_2, @set_3).should == 9
+    @set_1.redis.smembers(UNIONSTORE_KEY).sort.should == ['a','b','c','d','e','f','g','l','m']
 
-    # should get the lock because it has expired
-    gotit.should be_true
-    $redis.get("test_lock").should be_nil
+    (@set_1 ^ @set_2).sort.should == ["a", "b"]
+    (@set_1 - @set_2).sort.should == ["a", "b"]
+    (@set_2 - @set_1).sort.should == ["f", "g"]
+    @set_1.difference(@set_2).sort.should == ["a", "b"]
+    @set_1.diff(@set_2).sort.should == ["a", "b"]
+    @set_1.difference(@set_2, @set_3).sort.should == ['b']
+    @set_1.diffstore(DIFFSTORE_KEY, @set_2).should == 2
+    @set_1.redis.smembers(DIFFSTORE_KEY).sort.should == ['a','b']
+    @set_1.diffstore(DIFFSTORE_KEY, @set_2, @set_3).should == 1
+    @set_1.redis.smembers(DIFFSTORE_KEY).sort.should == ['b']
   end
 
-  it "should not let non-expired locks be gettable" do
-    expiry = 15
-    lock = Redis::Lock.new(:test_lock, $redis, :expiration => expiry, :timeout => 0.1, :init => false)
-
-    # create a fake lock
-    $redis.set("test_lock", (Time.now + expiry).to_f)
-
-    gotit = false
-    error = nil
-    begin
-      lock.lock do
-        gotit = true
-      end
-    rescue => error
-    end
-
-    error.should be_kind_of(Redis::Lock::LockTimeout)
-
-    # should not have the lock
-    gotit.should_not be_true
-
-    # lock value should still be set
-    $redis.get("test_lock").should_not be_nil
+  it "should support renaming sets" do
+    @set.should be_empty
+    @set['zynga'] = 151
+    @set['playfish'] = 202
+    @set.members.should == ['zynga','playfish']
+    @set.key.should == 'spec/zset'
+    @set.rename('spec/zset2').should be_true
+    @set.key.should == 'spec/zset2'
+    old = Redis::SortedSet.new('spec/zset')
+    old.should be_empty
+    old['tuff'] = 54
+    @set.renamenx('spec/zset').should be_false
+    @set.renamenx(old).should be_false
+    @set.renamenx('spec/zfoo').should be_true
+    @set.clear
+    @set.redis.del('spec/zset2')
   end
 
-  it "should not remove the key if lock is held past expiration" do
-    lock = Redis::Lock.new(:test_lock, $redis, :expiration => 0.0, :init => false)
-
-    lock.lock do
-      sleep 1.1
-    end
-
-    # lock value should still be set since the lock was held for more than the expiry
-    $redis.get("test_lock").should_not be_nil
+  after :all do
+    @set.clear
+    @set_1.clear
+    @set_2.clear
+    @set_3.clear
   end
-
-end
+end

data/spec/redis_objects_model_spec.rb

@@ -58,7 +58,7 @@ describe Redis::Objects do
 
   it "should provide a connection method" do
     Roster.redis.should == Redis::Objects.redis
-    Roster.redis.should be_kind_of(Redis)
+    # Roster.redis.should be_kind_of(Redis)
   end
 
   it "should create counter accessors" do

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: redis-objects
 version: !ruby/object:Gem::Version 
-  version: 0.2.3
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 4
+  version: 0.2.4
 platform: ruby
 authors: 
 - Nate Wiger
@@ -9,19 +14,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-18 00:00:00 -08:00
+date: 2010-04-09 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: redis
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: "0.1"
-    version: 
+        segments: 
+        - 1
+        - 0
+        - 3
+        version: 1.0.3
+  type: :runtime
+  version_requirements: *id001
 description: Map Redis types directly to Ruby objects. Works with any class or ORM.
 email: nate@wiger.org
 executables: []
@@ -42,9 +51,11 @@ files:
 - lib/redis/objects/lists.rb
 - lib/redis/objects/locks.rb
 - lib/redis/objects/sets.rb
+- lib/redis/objects/sorted_sets.rb
 - lib/redis/objects/values.rb
 - lib/redis/objects.rb
 - lib/redis/set.rb
+- lib/redis/sorted_set.rb
 - lib/redis/value.rb
 - spec/redis_objects_instance_spec.rb
 - spec/redis_objects_model_spec.rb
@@ -66,18 +77,20 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: 
-- redis, v0.1 or greater
+- redis, v1.0.3 or greater
 rubyforge_project: redis-objects
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Maps Redis types to Ruby objects