redis-objects 0.6.1 → 0.7.0

data/CHANGELOG.rdoc

@@ -1,6 +1,22 @@
 = Changelog for Redis::Objects
 
-== 0.6.0 (24 October 2012)
+== 0.7.0 (27 Feb 2013)
+
+* Enable inheritance of Redis::Objects models [rossta]
+
+* Finally fix require/autoload so "require 'redis/foo'" is not needed [nateware]
+
+* Redis::Objects.redis= now properly sets subclass handles as expected [nateware]
+
+* Add lib/redis-objects.rb for easier Gemfile require [notEthan]
+
+* Fix wrong readme line, fix some indentation [giglemad]
+
+== 0.6.1 (13 Dec 2012)
+
+* Fixed error that incorrectly specified activerecord as a gem dep [nateware]
+
+== 0.6.0 (13 Dec 2012)
 
 * Add +@set.merge()+ method to add multiple members at once [hfwang] 
 
@@ -24,7 +40,7 @@
 
 * group_set_with_scores is no longer needed.
 
-== 0.5.2 (13 June 2012)
+== 0.5.2 (13 Jun 2012)
 
 * Added Redis::SortedSet#member? method [Karl Varga]
 
@@ -40,7 +56,7 @@
 
 * Updated URLs to reflect new redis.io website [Jérémy Lecour]
 
-== 0.5.0 (8 November 2010)
+== 0.5.0 (8 Nov 2010)
 
 * Incompatible change: Had to rename Redis::Hash to Redis::HashKey due to internal conflicts with Redis lib and Ruby [Nate Wiger]
 
@@ -54,7 +70,7 @@
 
 * Updated Redis DEL semantics per API change [Gabe da Silveira]
 
-== 0.4.1 (23 August 2010)
+== 0.4.1 (23 Aug 2010)
 
 * Fixes for Ruby 1.8 failures due to missing flatten() [Gabe da Silveira]
 
@@ -64,7 +80,7 @@
 
 * Fixed a typo in delete_if and added missing test coverage [Julio Capote, Nate Wiger]
 
-== 0.4.0 (11 August 2010)
+== 0.4.0 (11 Aug 2010)
 
 * Full support for redis hashes via new Redis::Hash class [Julio Capote, Nate Wiger]
 
@@ -78,7 +94,7 @@
 
 * Renamed :withscores option to :with_scores for consistency with redis-rb 2.0, but kept backwards compat [Tom Stuart, Nate Wiger]
 
-== 0.3.2 (21 July 2010)
+== 0.3.2 (21 Jul 2010)
 
 * New "maxlength" option to Redis::List can create length-limited lists (eg, like a ring buffer) from dbalatero [David Balatero]
 
@@ -86,21 +102,21 @@
 
 * Switched from rspec to bacon for tests
 
-== 0.3.1 (1 June 2010)
+== 0.3.1 (1 Jun 2010)
 
 * Integrated fixes for sorted_set deletions from capotej [Julio Capote]
 
-== 0.3.0 (14 April 2010)
+== 0.3.0 (14 Apr 2010)
 
 * Due to Ruby 1.9 bugs and performance considerations, marshaling of data types is now OFF by default.  You must say :marshal => true for any objects that you want serialization enabled on. [Nate Wiger]
 
 * Sorted Set class changed slightly due to feedback. You can now get an individual element back via @set['item'] since it acts like a Hash.
 
-== 0.2.4 (9 April 2010)
+== 0.2.4 (9 Apr 2010)
 
 * Added sorted set support via Redis::SortedSet [Nate Wiger]
 
-== 0.2.3 (18 February 2010)
+== 0.2.3 (18 Feb 2010)
 
 * Added lock expiration to Redis::Lock [Ben VandenBos]
 
@@ -108,7 +124,7 @@
 
 * Added lock tests and test helpers [Ben VandenBos]
 
-== 0.2.2 (14 December 2009)
+== 0.2.2 (14 Dec 2009)
 
 * Added @set.diff(@set2) with "^" and "-" synonyms (oversight). [Nate Wiger]
 
@@ -118,7 +134,7 @@
 
 * More spec coverage. [Nate Wiger]
 
-== 0.2.1 (27 November 2009)
+== 0.2.1 (27 Nov 2009)
 
 * First worthwhile public release, with good spec coverage and functionality. [Nate Wiger]
 

data/{README.rdoc → README.md}

@@ -1,14 +1,15 @@
-= Redis::Objects - Map Redis types directly to Ruby objects
+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 is that it allows you to perform _atomic_ operations
-on _individual_ data structures, like counters, lists, and sets.  The *atomic* part is HUGE.
+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://redis.io/commands]
-to Ruby objects, via a thin layer over Ezra's +redis+ gem.  It offers several advantages
+This gem provides a Rubyish interface to Redis, by mapping [Redis types](http://redis.io/commands)
+to Ruby objects, via a thin layer over the `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!
@@ -17,42 +18,79 @@ over the lower-level redis-rb API:
 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 {An Atomic Rant}[http://nateware.com/2010/02/18/an-atomic-rant],
-or scroll down to "Atomicity" in this README.
+for a fun rant on the topic, see [An Atomic Rant](http://nateware.com/2010/02/18/an-atomic-rant),
+or scroll down to [Atomic Counters and Locks](#atomicity) in this README.
 
 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
-
+Installation and Setup
+----------------------
 Add it to your Gemfile as:
 
-    gem 'redis-objects', :require => 'redis/objects'
+    gem 'redis-objects'
+
+**Redis::Objects** needs a handle created by `Redis.new`. The recommended approach
+is to set `Redis.current` to point to your server, which **Redis::Objects** will
+pick up automatically.
+
+    require 'redis/objects'
+    Redis.current = Redis.new(:host => '127.0.0.1', :port => 6379)
+
+(If you're on Rails, `config/initializers/redis.rb` is a good place for this.)
+Remember you can use **Redis::Objects** in any Ruby code.  There are **no** dependencies
+on Rails.  Standalone, Sinatra, Resque - no problem.
+
+Alternatively, you can set the `redis` handle directly:
+
+    Redis::Objects.redis = Redis.new(...)
 
-== Example 1: Model Class Usage
+Finally, you can even setup different handles for different classes:
 
+    class User
+      include Redis::Objects
+    end
+    class Post
+      include Redis::Objects
+    end
+
+    User.redis = Redis.new(...)
+    Post.redis = Redis.new(...)
+
+As of `0.7.0`, `redis-objects` now autoloads the appropriate `Redis::Whatever`
+classes on demand.  Previous strategies of individually requiring `redis/list`
+or `redis/set` are no longer required.
+
+There are two ways to use **Redis::Objects**: As part of an model class (ActiveRecord,
+DataMapper, Mongoid, etc) or as standalong data type classes (`Redis::Set`, `Redis::List`, etc).
+
+Option 1: Model Class Usage
+============================
 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
+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 then automatically create keys that are unique to
 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.)
+For illustration purposes, consider this stub class:
 
-    require 'redis'
-    require 'redis/objects'
-    Redis.current = Redis.new(:host => '127.0.0.1', :port => 6379)
-
-Remember you can use Redis::Objects in any Ruby code.  There are *no* dependencies
-on Rails.  Standalone, Sinatra, Resque - no problem.
+    class User
+      include Redis::Objects
+      counter :my_posts
+      def id
+        1
+      end
+    end
 
-=== Model Class
+    user = User.new
+    user.id  # 1
+    user.my_posts.increment
+    user.my_posts.increment
+    user.my_posts.increment
+    puts user.my_posts  # 3
 
 You can include Redis::Objects in any type of class:
 
@@ -60,15 +98,16 @@ You can include Redis::Objects in any type of class:
       include Redis::Objects
 
       lock :trade_players, :expiration => 15  # sec
+      value :at_bat
       counter :hits
       counter :runs
       counter :outs
       counter :inning, :start => 1
       list :on_base
-      set :outfielders
-      value :at_bat
-      sorted_set :rank, :global => true
+      list :coaches, :marshal => true
+      set  :outfielders
       hash_key :pitchers_faced  # "hash" is taken by Ruby
+      sorted_set :rank, :global => true
     end
 
 Familiar Ruby array operations Just Work (TM):
@@ -106,44 +145,31 @@ Counters can be atomically incremented/decremented (but not assigned):
     @team.hits.incr(3)    # add 3
     @team.runs = 4        # exception
 
-Finally, for free, you get a +redis+ method that points directly to a Redis connection:
+Finally, for free, you get a `redis` method that points directly to a Redis connection:
 
     Team.redis.get('somekey')
     @team = Team.new
     @team.redis.get('somekey')
     @team.redis.smembers('someset')
 
-You can use the +redis+ handle to directly call any {Redis API command}[http://redis.io/commands].
-
-== Example 2: Standalone Usage
+You can use the `redis` handle to directly call any [Redis API command](http://redis.io/commands).
 
+Option 2: Standalone Usage
+===========================
 There is a Ruby class that maps to each Redis type, with methods for each
-{Redis API command}[http://redis.io/commands].
-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
-
-Redis::Objects needs a handle to the +redis+ server.  For standalone use, you
-can either set Redis.current:
-
-    Redis.current = Redis.new(:host => 'localhost', :port => 6379)
-    @list = Redis::List.new('mylist')
-
-Or you can pass the Redis handle into the new method for each type:
+[Redis API command](http://redis.io/commands).
+Note that calling `new` does not imply it's actually a "new" value - it just
+creates a mapping between that Ruby object and the corresponding Redis data
+structure, which may already exist on the `redis-server`.
 
-    @redis = Redis.new(:host => 'localhost', :port => 6379)
-    @list = Redis::List.new('mylist', @redis)
+Counters
+--------
+The `counter_name` is the key stored in Redis.
 
-=== Counters
-
-Create a new counter. The +counter_name+ is the key stored in Redis.
-
-    require 'redis/counter'
     @counter = Redis::Counter.new('counter_name')
-    @counter.increment
-    @counter.decrement
+    @counter.increment  # or incr
+    @counter.decrement  # or decr
+    @counter.increment(3)
     puts @counter.value
 
 This gem provides a clean way to do atomic blocks as well:
@@ -152,25 +178,23 @@ This gem provides a clean way to do atomic blocks as well:
       raise "Full" if val > MAX_VAL  # rewind counter
     end
 
-See the section on "Atomicity" for cool uses of atomic counter blocks.
-
-=== Locks
+See the section on [Atomic Counters and Locks](#atomicity) for cool uses of atomic counter blocks.
 
-A convenience class that wraps the pattern of {using +setnx+ to perform locking}[http://redis.io/commands/setnx].
+Locks
+-----
+A convenience class that wraps the pattern of [using setnx to perform locking](http://redis.io/commands/setnx).
 
-    require 'redis/lock'
-    @lock = Redis::Lock.new('image_resizing', :expiration => 15, :timeout => 0.1)
+    @lock = Redis::Lock.new('serialize_stuff', :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
-
+Values
+------
 Simple values are easy as well:
 
-    require 'redis/value'
     @value = Redis::Value.new('value_name')
     @value.value = 'a'
     @value.delete
@@ -182,11 +206,10 @@ Complex data is no problem with :marshal => true:
     @newest.value = @account.attributes
     puts @newest.value['username']
 
-=== Lists
-
+Lists
+-----
 Lists work just like Ruby arrays:
 
-    require 'redis/list'
     @list = Redis::List.new('list_name')
     @list << 'a'
     @list << 'b'
@@ -205,9 +228,9 @@ Lists work just like Ruby arrays:
 You can bound the size of the list to only hold N elements like so:
 
     # Only holds 10 elements, throws out old ones when you reach :maxlength.
-    @list = Redis::List.new('list_name', redis_handle, :maxlength => 10)
+    @list = Redis::List.new('list_name', :maxlength => 10)
 
-Complex data types are no problem with :marshal => true:
+Complex data types are no handled with :marshal => true:
 
     @list = Redis::List.new('list_name', :marshal => true)
     @list << {:name => "Nate", :city => "San Diego"}
@@ -216,13 +239,12 @@ Complex data types are no problem with :marshal => true:
       puts "#{el[:name]} lives in #{el[:city]}"
     end
 
-=== Hashes
-
-Hashes work like a Ruby {Hash}[http://ruby-doc.org/core/classes/Hash.html], with
+Hashes
+------
+Hashes work like a Ruby [Hash](http://ruby-doc.org/core/classes/Hash.html), with
 a few Redis-specific additions.  (The class name is "HashKey" not just "Hash", due to
 conflicts with the Ruby core Hash class in other gems.)
 
-    require 'redis/hash_key'
     @hash = Redis::HashKey.new('hash_name')
     @hash['a'] = 1
     @hash['b'] = 2
@@ -239,13 +261,15 @@ Redis also adds incrementing and bulk operations:
     @hash.bulk_set('d' => 5, 'e' => 6)
     @hash.bulk_get('d','e')  # "5", "6"
 
-Remember that numbers become strings in Redis.  Unlike with other Redis data types, redis-objects can't guess at your data type in this situation.
+Remember that numbers become strings in Redis.  Unlike with other Redis data types,
+`redis-objects` can't guess at your data type in this situation, since you may
+actually mean to store "1.5".
 
-=== Sets
+Sets
+----
+Sets work like the Ruby [Set](http://ruby-doc.org/core/classes/Set.html) class.
+They are unordered, but guarantee uniqueness of members.
 
-Sets work like the Ruby {Set}[http://ruby-doc.org/core/classes/Set.html] class:
-
-    require 'redis/set'
     @set = Redis::Set.new('set_name')
     @set << 'a'
     @set << 'b'
@@ -286,21 +310,20 @@ And use complex data types too, with :marshal => true:
 
     @set1 = Redis::Set.new('set1', :marshal => true)
     @set2 = Redis::Set.new('set2', :marshal => true)
-    @set1 << {:name => "Nate", :city => "San Diego"}
+    @set1 << {:name => "Nate",  :city => "San Diego"}
     @set1 << {:name => "Peter", :city => "Oceanside"}
-    @set2 << {:name => "Nate", :city => "San Diego"}
-    @set2 << {:name => "Jeff", :city => "Del Mar"}
+    @set2 << {:name => "Nate",  :city => "San Diego"}
+    @set2 << {:name => "Jeff",  :city => "Del Mar"}
 
     @set1 & @set2  # Nate
     @set1 - @set2  # Peter
     @set1 | @set2  # all 3 people
 
-=== Sorted Sets
-
+Sorted Sets
+-----------
 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/sorted_set'
     @sorted_set = Redis::SortedSet.new('number_of_posts')
     @sorted_set['Nate']  = 15
     @sorted_set['Peter'] = 75
@@ -333,13 +356,13 @@ a Hash and an Array.  You assign like a Hash, but retrieve like an Array:
     @sorted_set.incr('Peter')   # shorthand
     @sorted_set.incr('Jeff', 4)
 
-The other Redis Sorted Set commands are supported as well; see {Sorted Sets API}[http://redis.io/commands#sorted_set].
-
-== Atomic Counters and Locks
+The other Redis Sorted Set commands are supported as well; see [Sorted Sets API](http://redis.io/commands#sorted_set).
 
+<a name="atomicity"></a>
+Atomic Counters and Locks
+-------------------------
 You are probably not handling atomicity correctly in your app.  For a fun rant
-on the topic, see
-{An Atomic Rant}[http://nateware.com/2010/02/18/an-atomic-rant].
+on the topic, see [An Atomic Rant](http://nateware.com/an-atomic-rant.html).
 
 Atomic counters are a good way to handle concurrency:
 
@@ -353,16 +376,16 @@ Atomic counters are a good way to handle concurrency:
       @team.drafted_players.decrement
     end
 
-Atomic block - a cleaner way to do the above. <b><em>Exceptions or returning nil
-rewind counter back to previous state</em></b>:
+An _atomic block_ gives you a cleaner way to do the above. Exceptions or returning nil
+will rewind the counter back to its previous state:
 
     @team.drafted_players.increment do |val|
-      raise Team::TeamFullError if val > @team.max_players
+      raise Team::TeamFullError if val > @team.max_players  # rewind
       @team.team_players.create!(:player_id => 221)
       @team.active_players.increment
     end
 
-Similar approach, using an if block (failure rewinds counter):
+Here's a similar approach, using an if block (failure rewinds counter):
 
     @team.drafted_players.increment do |val|
       if val <= @team.max_players
@@ -371,20 +394,23 @@ Similar approach, using an if block (failure rewinds counter):
       end
     end
 
-Class methods work too - notice we override ActiveRecord counters:
+Class methods work too, using the familiar ActiveRecord counter syntax:
 
     Team.increment_counter :drafted_players, team_id
     Team.decrement_counter :drafted_players, team_id, 2
     Team.increment_counter :total_online_players  # no ID on global counter
 
-Class-level atomic block (may save a DB fetch depending on your app):
+Class-level atomic blocks can also be used.  This may save a DB fetch, if you have
+a record ID and don't need any other attributes from the DB table:
 
     Team.increment_counter(:drafted_players, team_id) do |val|
       TeamPitcher.create!(:team_id => team_id, :pitcher_id => 181)
       Team.increment_counter(:active_players, team_id)
     end
 
-Locks with Redis. On completion or exception the lock is released:
+### Locks ###
+
+Locks work similarly. On completion or exception the lock is released:
 
     class Team < ActiveRecord::Base
       lock :reorder # declare a lock
@@ -410,9 +436,11 @@ lock time.
       lock :reorder, :expiration => 15.minutes
     end
 
+Keep in mind that true locks serialize your entire application at that point.  As
+such, atomic counters are strongly preferred.
 
-== Author
-
-Copyright (c) 2009-2012 {Nate Wiger}[http://nateware.com].  All Rights Reserved.
-Released under the {Artistic License}[http://www.opensource.org/licenses/artistic-license-2.0.php].
+Author
+=======
+Copyright (c) 2009-2013 [Nate Wiger](http://nateware.com).  All Rights Reserved.
+Released under the [Artistic License](http://www.opensource.org/licenses/artistic-license-2.0.php).