redis-objects 0.1.0 → 0.1.2

data/README.rdoc

@@ -1,16 +1,15 @@
-= Redis::Objects - Lightweight, atomic object layer around redis-rb
+= 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.
 
 The killer feature of Redis that it allows you to perform atomic operations
-on _individual_ data structures, like counters, lists, and sets, that you can use
-*with* your existing ActiveRecord/DataMapper/etc models, or in classes that have
+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.
 
-
-This gem originally arose out of a need for high-concurrency operations for online
-games; for a fun rant on the topic, see
+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.
 
@@ -23,6 +22,8 @@ by using +new+ with the type of data structure you want to create.
     gem tumble
     gem install redis-objects
    
+== Example 1: Class Usage
+
 === Initialization
 
     # If on Rails, config/initializers/redis.rb is a good place for this
@@ -30,51 +31,117 @@ by using +new+ with the type of data structure you want to create.
     require 'redis/objects'
     Redis::Objects.redis = Redis.new(:host => 127.0.0.1, :port => 6379)
 
-== Examples
+=== Model Class
 
-=== Model Class Usage
+Include in any type of class:
 
     class Team < ActiveRecord::Base
       include Redis::Objects
       
-      counter :drafted_players
-      counter :active_players
-      counter :total_online_players, :global => true
+      counter :hits
+      counter :runs
+      counter :outs
+      counter :inning, :start => 1
       list :on_base
       set :outfielders
-      value :coach
+      value :at_bat
     end
     
-Familiar Ruby operations Just Work:
+Familiar Ruby array operations Just Work (TM):
 
     @team = Team.find(1)
     @team.on_base << 'player1'
     @team.on_base << 'player2'
-    puts @team.on_base   # ['player1', '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'}
 
-With one purposeful exception - counters cannot be set, only incremented/decremented:
+Note counters cannot be assigned to, only incremented/decremented:
 
-    @team.drafted_players.increment  # or incr
-    @team.drafted_players.decrement  # or decr
-    @team.drafted_players = 4   # exception
-    @team.drafted_players += 1  # exception
+    @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.
+
+=== Initialization
 
-=== Instance Usage
+Can follow the +$redis+ global variable pattern:
+
+    $redis = Redis.new(:host => 'localhost', :port => 6379)
+    @value = Redis::Value.new('myvalue')
+
+Or can pass the handle into the new method:
+    
+    redis  = Redis.new(:host => 'localhost', :port => 6379)
+    @value = Redis::Value.new('myvalue', redis)
 
 === Counters
 
     @counter = Redis::Counter.new('counter_name')
     @counter.increment
-    puts @counter
-    puts @counter.get  # force re-fetch
+    @counter.decrement
+    puts @counter.value
+    @counter.increment do |val|
+      raise "Full" if val > MAX_VAL  # rewind counter
+    end
+
+See the section on "Atomicity" for cool uses of atomic counter blocks.
 
 === Lists
 
+These work just like Ruby arrays:
+
     @list = Redis::List.new('list_name')
     @list << 'a'
     @list << 'b'
-    puts @list
+    @list.include? 'c'   # false
+    @list.values  # ['a','b']
+    @list.shift
+    @list.pop
+    @list.clear
+    # etc
+
+=== Sets
+
+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.member? 'c'   # false
+    @set.members  # ['a','b']
+    @set.each do |member|
+      puts member
+    end
+    @set.clear
+    # etc
+
+=== Values
+
+    @value = Redis::Value.new('value_name')
+    @value.value = 'a'
+    @value.delete
 
 == Atomicity
 

data/lib/redis/counter.rb

@@ -8,12 +8,11 @@ class Redis
   #
   class Counter
     attr_reader :key, :options, :redis
-    def initialize(key, options={})
+    def initialize(key, redis=$redis, options={})
       @key = key
+      @redis = redis
       @options = options
-      @redis = options[:redis] || $redis || Redis::Objects.redis
       @options[:start] ||= 0
-      @options[:type]  ||= @options[:start] == 0 ? :increment : :decrement
       @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
     end
 

data/lib/redis/list.rb

@@ -4,92 +4,119 @@ class Redis
   # behave as much like Ruby arrays as possible.
   #
   class List
+    require 'enumerator'
+    include Enumerable
+
     attr_reader :key, :options, :redis
-    def initialize(key, options={})
+    def initialize(key, redis=$redis, options={})
       @key = key
+      @redis = redis
       @options = options
-      @redis   = options[:redis] || $redis || Redis::Objects.redis
-      @options[:start] ||= 0
-      @options[:type]  ||= @options[:start] == 0 ? :increment : :decrement
-      @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
     end
-
+    
+    # Works like push.  Can chain together: list << 'a' << 'b'
     def <<(value)
       push(value)
+      self  # for << 'a' << 'b'
     end
-    
+
+    # Add a member to the end of the list. Redis: RPUSH
     def push(value)
       redis.rpush(key, value)
-      @values << value
     end
 
+    # Remove a member from the end of the list. Redis: RPOP
     def pop
       redis.rpop(key)
-      @values.pop
     end
 
+    # Add a member to the start of the list. Redis: LPUSH
     def unshift(value)
       redis.lpush(key, value)
-      @values.unshift value
     end
 
+    # Remove a member from the start of the list. Redis: LPOP
     def shift
       redis.lpop(key)
     end
 
+    # Return all values in the list. Redis: LRANGE(0,-1)
     def values
-      @values ||= get
+      range(0, -1)
     end
+    alias_method :get, :values
 
-    def value=(val)
-      redis.set(key, val)
-      @values = val
-    end
-    
-    def get
-      @values = range(0, -1)
-    end
-    
-    def [](index)
-      case index
-      when Range
+    # Same functionality as Ruby arrays.  If a single number is given, return
+    # just the element at that index using Redis: LINDEX. Otherwise, return
+    # a range of values using Redis: LRANGE.
+    def [](index, length=nil)
+      if index.is_a? Range
         range(index.first, index.last)
+      elsif length
+        range(index, length)
       else
-        range(index, index)
+        at(index)
       end
     end
     
+    # Delete the element(s) from the list that match name. If count is specified,
+    # only the first-N (if positive) or last-N (if negative) will be removed.
+    # Redis: LREM
     def delete(name, count=0)
-      redis.lrem(name, count)
+      redis.lrem(key, count, name)  # weird api
+      get
+    end
+
+    # Iterate through each member of the set.  Redis::Objects mixes in Enumerable,
+    # so you can also use familiar methods like +collect+, +detect+, and so forth.
+    def each(&block)
+      values.each(&block)
     end
 
+    # Return a range of values from +start_index+ to +end_index+.  Can also use
+    # the familiar list[start,end] Ruby syntax. Redis: LRANGE
     def range(start_index, end_index)
       redis.lrange(key, start_index, end_index)
     end
- 
+
+    # Return the value at the given index. Can also use familiar list[index] syntax.
+    # Redis: LINDEX
     def at(index)
-      redis.lrange(key, index, index)
+      redis.lindex(key, index)
+    end
+
+    # Return the first element in the list. Redis: LINDEX(0)
+    def first
+      at(0)
     end
 
+    # Return the last element in the list. Redis: LINDEX(-1)
     def last
-      redis.lrange(key, -1, -1)
+      at(-1)
     end
 
+    # Clear the list entirely. Redis: DEL
     def clear
       redis.del(key)
     end
 
+    # Return the length of the list. Aliased as size. Redis: LLEN
     def length
-      redis.length
+      redis.llen(key)
     end
     alias_method :size, :length
-    
+   
+    # Returns true if there are no elements in the list. Redis: LLEN == 0
     def empty?
-      values.empty?
+      length == 0
     end
-    
+ 
     def ==(x)
       values == x
     end
+    
+    def to_s
+      values.join(', ')
+    end
   end
 end

data/lib/redis/lock.rb

@@ -10,11 +10,11 @@ class Redis
     class LockTimeout < StandardError; end #:nodoc:
 
     attr_reader :key, :options, :redis
-    def initialize(key, options={})
+    def initialize(key, redis=$redis, options={})
       @key = key
+      @redis = redis
       @options = options
       @options[:timeout] ||= 5
-      @redis = options[:redis] || $redis || Redis::Objects.redis
       @redis.setnx(key, @options[:start]) unless @options[:start] == 0 || @options[:init] === false
     end
 

data/lib/redis/objects/counters.rb

@@ -24,7 +24,7 @@ class Redis
           @counters[name] = options
           class_eval <<-EndMethods
             def #{name}
-              @#{name} ||= Redis::Counter.new(field_key(:#{name}), self.class.counters[:#{name}].merge(:redis => redis))
+              @#{name} ||= Redis::Counter.new(field_key(:#{name}), redis, self.class.counters[:#{name}])
             end
           EndMethods
         end

data/lib/redis/objects/lists.rb

@@ -20,7 +20,7 @@ class Redis
           @lists[name] = options
           class_eval <<-EndMethods
             def #{name}
-              @#{name} ||= Redis::List.new(field_key(:#{name}), self.class.lists[:#{name}].merge(:redis => redis))
+              @#{name} ||= Redis::List.new(field_key(:#{name}), redis, self.class.lists[:#{name}])
             end
           EndMethods
         end

data/lib/redis/objects/locks.rb

@@ -22,7 +22,7 @@ class Redis
           @locks[name] = options
           class_eval <<-EndMethods
             def #{name}_lock(&block)
-              @#{name}_lock ||= Redis::Lock.new(field_key(:#{name}_lock), self.class.locks[:#{name}].merge(:redis => redis))
+              @#{name}_lock ||= Redis::Lock.new(field_key(:#{name}_lock), redis, self.class.locks[:#{name}])
             end
           EndMethods
         end

data/lib/redis/objects/sets.rb

@@ -4,6 +4,31 @@ require 'redis/set'
 class Redis
   module Objects
     module Sets
+      def self.included(klass)
+        klass.instance_variable_set('@sets', {})
+        klass.send :include, InstanceMethods
+        klass.extend ClassMethods
+      end
+
+      # Class methods that appear in your class when you include Redis::Objects.
+      module ClassMethods
+        attr_reader :sets
+
+        # Define a new list.  It will function like a regular instance
+        # method, so it can be used alongside ActiveRecord, DataMapper, etc.
+        def set(name, options={})
+          @sets[name] = options
+          class_eval <<-EndMethods
+            def #{name}
+              @#{name} ||= Redis::Set.new(field_key(:#{name}), redis, self.class.sets[:#{name}])
+            end
+          EndMethods
+        end
+      end
+
+      # Instance methods that appear in your class when you include Redis::Objects.
+      module InstanceMethods
+      end
     end
   end
 end

data/lib/redis/objects/values.rb

@@ -20,7 +20,7 @@ class Redis
           @values[name] = options
           class_eval <<-EndMethods
             def #{name}
-              @#{name} ||= Redis::Value.new(field_key(:#{name}), self.class.values[:#{name}].merge(:redis => redis))
+              @#{name} ||= Redis::Value.new(field_key(:#{name}), redis, self.class.values[:#{name}])
             end
             def #{name}=(value)
               #{name}.value = value

data/lib/redis/set.rb

@@ -3,5 +3,74 @@ class Redis
   # Class representing a set.
   #
   class Set
+    require 'enumerator'
+    include Enumerable
+
+    attr_reader :key, :options, :redis
+    def initialize(key, redis=$redis, options={})
+      @key = key
+      @redis = redis
+      @options = options
+    end
+
+    # Works like add.  Can chain together: list << 'a' << 'b'
+    def <<(value)
+      add(value)
+      self  # for << 'a' << 'b'
+    end
+    
+    # Add the specified value to the set only if it does not exist already.
+    # Redis: SADD
+    def add(value)
+      redis.sadd(key, value)
+    end
+
+    # Return all members in the set.  Redis: SMEMBERS
+    def members
+      redis.smembers(key)
+    end
+    alias_method :get, :members
+
+    # Returns true if the specified value is in the set.  Redis: SISMEMBER
+    def member?(value)
+      redis.sismember(key, value)
+    end
+    alias_method :include?, :member?
+
+    # Delete the value from the set.  Redis: SREM
+    def delete(name)
+      redis.srem(key, name)
+      get
+    end
+
+    # Wipe the set entirely.  Redis: DEL
+    def clear
+      redis.del(key)
+    end
+
+    # Iterate through each member of the set.  Redis::Objects mixes in Enumerable,
+    # so you can also use familiar methods like +collect+, +detect+, and so forth.
+    def each(&block)
+      members.each(&block)
+    end
+
+    # The number of members in the set. Aliased as size. Redis: SCARD
+    def length
+      redis.scard(key)
+    end
+    alias_method :size, :length
+
+    # 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
   end
 end

data/lib/redis/value.rb

@@ -4,10 +4,10 @@ class Redis
   #
   class Value
     attr_reader :key, :options, :redis
-    def initialize(key, options={})
+    def initialize(key, redis=$redis, options={})
       @key = key
+      @redis = redis
       @options = options
-      @redis   = options[:redis] || $redis || Redis::Objects.redis
       @redis.setnx(key, @options[:default]) if @options[:default]
     end
 

data/spec/redis_objects_model_spec.rb

@@ -10,6 +10,7 @@ class Roster
   lock :resort, :timeout => 2
   value :starting_pitcher
   list :player_stats
+  set :outfielders
 
   def initialize(id=1) @id = id end
   def id; @id; end
@@ -29,6 +30,7 @@ describe Redis::Objects do
     @roster.resort_lock.clear
     @roster.starting_pitcher.delete
     @roster.player_stats.clear
+    @roster.outfielders.clear
   end
 
   it "should provide a connection method" do
@@ -254,6 +256,110 @@ describe Redis::Objects do
     @roster.player_stats.should be_empty
     @roster.player_stats << 'a'
     @roster.player_stats.should == ['a']
+    @roster.player_stats.get.should == ['a']
+    @roster.player_stats.unshift 'b'
+    @roster.player_stats.to_s.should == 'b, a'
+    @roster.player_stats.should == ['b','a']
+    @roster.player_stats.get.should == ['b','a']
+    @roster.player_stats.push 'c'
+    @roster.player_stats.should == ['b','a','c']
+    @roster.player_stats.get.should == ['b','a','c']
+    @roster.player_stats.first.should == 'b'
+    @roster.player_stats.last.should == 'c'
+    @roster.player_stats << 'd'
+    @roster.player_stats.should == ['b','a','c','d']
+    @roster.player_stats[1].should == 'a'
+    @roster.player_stats[0].should == 'b'
+    @roster.player_stats[2].should == 'c'
+    @roster.player_stats[3].should == 'd'
+    @roster.player_stats.include?('c').should be_true
+    @roster.player_stats.include?('no').should be_false
+    @roster.player_stats.pop
+    @roster.player_stats[0].should == @roster.player_stats.at(0)
+    @roster.player_stats[1].should == @roster.player_stats.at(1)
+    @roster.player_stats[2].should == @roster.player_stats.at(2)
+    @roster.player_stats.should == ['b','a','c']
+    @roster.player_stats.get.should == ['b','a','c']
+    @roster.player_stats.shift
+    @roster.player_stats.should == ['a','c']
+    @roster.player_stats.get.should == ['a','c']
+    @roster.player_stats << 'e' << 'f' << 'e'
+    @roster.player_stats.should == ['a','c','e','f','e']
+    @roster.player_stats.get.should == ['a','c','e','f','e']
+    @roster.player_stats.delete('e')
+    @roster.player_stats.should == ['a','c','f']
+    @roster.player_stats.get.should == ['a','c','f']
+    @roster.player_stats << 'j'
+    @roster.player_stats.should == ['a','c','f','j']
+    @roster.player_stats[0..2].should == ['a','c','f']
+    @roster.player_stats[1, 3].should == ['c','f','j']
+    @roster.player_stats.length.should == 4
+    @roster.player_stats.size.should == 4
+    @roster.player_stats.should == ['a','c','f','j']
+    @roster.player_stats.get.should == ['a','c','f','j']
+
+    i = -1
+    @roster.player_stats.each do |st|
+      st.should == @roster.player_stats[i += 1]
+    end
+    @roster.player_stats.should == ['a','c','f','j']
+    @roster.player_stats.get.should == ['a','c','f','j']
+
+    @roster.player_stats.each_with_index do |st,i|
+      st.should == @roster.player_stats[i]
+    end
+    @roster.player_stats.should == ['a','c','f','j']
+    @roster.player_stats.get.should == ['a','c','f','j']
+
+    coll = @roster.player_stats.collect{|st| st}
+    coll.should == ['a','c','f','j']
+    @roster.player_stats.should == ['a','c','f','j']
+    @roster.player_stats.get.should == ['a','c','f','j']
+
+    @roster.player_stats << 'a'
+    coll = @roster.player_stats.select{|st| st == 'a'}
+    coll.should == ['a','a']
+    @roster.player_stats.should == ['a','c','f','j','a']
+    @roster.player_stats.get.should == ['a','c','f','j','a']
+  end
+
+  it "should handle sets of simple values" do
+    @roster.outfielders.should be_empty
+    @roster.outfielders << 'a' << 'a' << 'a'
+    @roster.outfielders.should == ['a']
+    @roster.outfielders.get.should == ['a']
+    @roster.outfielders << 'b' << 'b'
+    @roster.outfielders.to_s.should == 'a, b'
+    @roster.outfielders.should == ['a','b']
+    @roster.outfielders.members.should == ['a','b']
+    @roster.outfielders.get.should == ['a','b']
+    @roster.outfielders << 'c'
+    @roster.outfielders.sort.should == ['a','b','c']
+    @roster.outfielders.get.sort.should == ['a','b','c']
+    @roster.outfielders.delete('c')
+    @roster.outfielders.should == ['a','b']
+    @roster.outfielders.get.sort.should == ['a','b']
+    @roster.outfielders.length.should == 2
+    @roster.outfielders.size.should == 2
+    
+    i = 0
+    @roster.outfielders.each do |st|
+      i += 1
+    end
+    i.should == @roster.outfielders.length
+
+    coll = @roster.outfielders.collect{|st| st}
+    coll.should == ['a','b']
+    @roster.outfielders.should == ['a','b']
+    @roster.outfielders.get.should == ['a','b']
+
+    @roster.outfielders << 'c'
+    @roster.outfielders.member?('c').should be_true
+    @roster.outfielders.include?('c').should be_true
+    @roster.outfielders.member?('no').should be_false
+    coll = @roster.outfielders.select{|st| st == 'c'}
+    coll.should == ['c']
+    @roster.outfielders.sort.should == ['a','b','c']
   end
 
   it "should provide a lock method that accepts a block" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: redis-objects
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors: 
 - Nate Wiger
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-24 00:00:00 -08:00
+date: 2009-11-26 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
-description: Redis::Objects is a lightweight library that lets you use Redis primitives as Ruby objects from any class or ORM
+description: Map Redis types directly to Ruby objects. Works with any class or ORM.
 email: nate@wiger.org
 executables: []
 
@@ -68,6 +68,6 @@ rubyforge_project: redis-objects
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Lightweight map of Redis types to Ruby objects
+summary: Maps Redis types to Ruby objects
 test_files: []