redis 0.2.0 → 1.0.0

data/README.markdown

@@ -1,36 +1,74 @@
 # redis-rb
 
-A ruby client library for the redis key value storage system.
+A Ruby client library for the [Redis](http://code.google.com/p/redis) key-value storage system.
 
-## Information about redis
+## Information about Redis
 
-Redis is a key value store with some interesting features:
-1. It's fast.
-2. Keys are strings but values can have types of "NONE", "STRING", "LIST",  or "SET".  List's can be atomically push'd, pop'd, lpush'd, lpop'd and indexed.  This allows you to store things like lists of comments under one key while retaining the ability to append comments without reading and putting back the whole list.
-
-See [redis on code.google.com](http://code.google.com/p/redis/wiki/README) for more information.
-
-See the build on [RunCodeRun](http://runcoderun.com/rsanheim/redis-rb)
+Redis is a key-value store with some interesting features:
 
-## Dependencies
-
-1. rspec - 
-		sudo gem install rspec
-
-2. redis - 
+1. It's fast.
+2. Keys are strings but values are typed. Currently Redis supports strings, lists, sets, sorted sets and hashes. [Atomic operations](http://code.google.com/p/redis/wiki/CommandReference) can be done on all of these types.
+
+See [the Redis homepage](http://code.google.com/p/redis/wiki/README) for more information.
+
+## Usage
+
+For all types redis-rb needs redis-server running to connect to.
+
+### Simple Key Value Strings can be used like a large Ruby Hash (Similar to Memcached, Tokyo Cabinet)
+	
+	require 'redis'
+	r = Redis.new
+	r['key_one'] = "value_one"
+	r['key_two'] = "value_two"
+	
+	r['key_one]  # => "value_one"
+
+### Redis only stores strings. To store Objects, Array or Hashes, you must [Marshal](http://ruby-doc.org/core/classes/Marshal.html)
+	
+	require 'redis'
+	r = Redis.new
+	
+	example_hash_to_store = {:name => "Alex", :age => 21, :password => "letmein", :cool => false}
+	
+	r['key_one'] = Marshal.dump(example_hash_to_store)
+	
+	hash_returned_from_redis = Marshal.load(r['key_one'])
+	
+### Alternatively you can use the [Redis Commands](http://code.google.com/p/redis/wiki/CommandReference)
+	
+	require 'redis'
+	r = Redis.new
+	r.set 'key_one', 'value_one'
+	r.get 'key_one' # => 'value_one'
+	
+	# Using Redis list objects
+	# Push an object to the head of the list. Creates the list if it doesn't allready exsist.
+	
+	blog_hash = {:title => "Redis Rules!", :body => "Ok so, like why, well like, RDBMS is like....", :created_at => Time.now.to_i}
+	r.lpush 'all_blogs', Marshal.dump(blog_hash)
+	
+	# Get a range of strings from the all_blogs list. Similar to offset and limit in SQL (-1, means the last one)
+	
+	r.lrange 'all_blogs', 0, -1
+
+### Multiple commands at once!
+
+	require 'redis'
+	r = Redis.new
+	r.multi do
+	  r.set 'foo', 'bar'
+	  r.incr 'baz'
+	end
+
+## Contributing
+
+See the build on [RunCodeRun](http://runcoderun.com/rsanheim/redis-rb).
+
+If you would like to submit patches, you'll need Redis in your development environment:
 
 		rake redis:install
 
-2. dtach - 
-
-		rake dtach:install
-
-3. git - git is the new black.
-
-## Setup
-
-Use the tasks mentioned above (in Dependencies) to get your machine setup.
-
 ## Examples
 
-Check the examples/ directory.  *Note* you need to have redis-server running first.
+Check the `examples/` directory. You'll need to have an instance of `redis-server` running before running the examples.

data/Rakefile

@@ -1,8 +1,6 @@
 require 'rubygems'
 require 'rake/gempackagetask'
-require 'rubygems/specification'
-require 'date'
-require 'spec/rake/spectask'
+require 'rake/testtask'
 require 'tasks/redis.tasks'
 
 $:.unshift File.join(File.dirname(__FILE__), 'lib')
@@ -10,7 +8,7 @@ require 'redis'
 
 GEM = 'redis'
 GEM_NAME = 'redis'
-GEM_VERSION = RedisRb::VERSION
+GEM_VERSION = Redis::VERSION
 AUTHORS = ['Ezra Zygmuntowicz', 'Taylor Weibley', 'Matthew Clark', 'Brian McKinney', 'Salvatore Sanfilippo', 'Luca Guidi']
 EMAIL = "ez@engineyard.com"
 HOMEPAGE = "http://github.com/ezmobius/redis-rb"
@@ -33,12 +31,10 @@ spec = Gem::Specification.new do |s|
   s.files = %w(LICENSE README.markdown Rakefile) + Dir.glob("{lib,tasks,spec}/**/*")
 end
 
-task :default => :spec
+task :default => :test
 
-desc "Run specs"
-Spec::Rake::SpecTask.new do |t|
-  t.spec_files = FileList['spec/**/*_spec.rb']
-  t.spec_opts = %w(-fs --color)
+Rake::TestTask.new(:test) do |t|
+  t.pattern = 'test/**/*_test.rb'
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
@@ -51,14 +47,8 @@ task :install => [:package] do
 end
 
 desc "create a gemspec file"
-task :make_spec do
+task :gemspec do
   File.open("#{GEM}.gemspec", "w") do |file|
     file.puts spec.to_ruby
   end
 end
-
-desc "Run all examples with RCov"
-Spec::Rake::SpecTask.new(:rcov) do |t|
-  t.spec_files = FileList['spec/**/*_spec.rb']
-  t.rcov = true
-end

data/lib/redis.rb

@@ -1,23 +1,24 @@
 require 'socket'
 
-module RedisRb
-  VERSION = "0.2.0"
+class Redis
+  VERSION = "1.0.0"
+
+  def self.new(*attrs)
+    Client.new(*attrs)
+  end
 end
 
 begin
   if RUBY_VERSION >= '1.9'
     require 'timeout'
-    RedisRb::RedisTimer = Timeout
+    Redis::Timer = Timeout
   else
     require 'system_timer'
-    RedisRb::RedisTimer = SystemTimer
+    Redis::Timer = SystemTimer
   end
 rescue LoadError
-  RedisRb::RedisTimer = nil
+  Redis::Timer = nil
 end
 
 require 'redis/client'
 require 'redis/pipeline'
-
-# For backwards compatibility
-Redis = RedisRb::Client

data/lib/redis/client.rb

@@ -1,4 +1,4 @@
-module RedisRb
+class Redis
   class Client
     OK      = "OK".freeze
     MINUS    = "-".freeze
@@ -28,7 +28,8 @@ module RedisRb
       "zrevrank"  => true,
       "hget"      => true,
       "hdel"      => true,
-      "hexists"   => true
+      "hexists"   => true,
+      "publish"   => true
     }
 
     MULTI_BULK_COMMANDS = {
@@ -134,29 +135,195 @@ module RedisRb
       @binary_keys = options[:binary_keys]
       @mutex = Mutex.new if @thread_safe
       @sock = nil
+      @pubsub = false
 
-      @logger.info { self.to_s } if @logger
+      log(self)
     end
 
     def to_s
       "Redis Client connected to #{server} against DB #{@db}"
     end
 
-    def server
-      "#{@host}:#{@port}"
+    def select(*args)
+      raise "SELECT not allowed, use the :db option when creating the object"
     end
 
-    def connect_to_server
-      @sock = connect_to(@host, @port, @timeout == 0 ? nil : @timeout)
-      call_command(["auth",@password]) if @password
-      call_command(["select",@db]) unless @db == 0
+    def [](key)
+      get(key)
+    end
+
+    def []=(key,value)
+      set(key, value)
+    end
+
+    def set(key, value, ttl = nil)
+      if ttl
+        deprecated("set with an expire", :set_with_expire, caller[0])
+        set_with_expire(key, value, ttl)
+      else
+        call_command([:set, key, value])
+      end
+    end
+
+    def set_with_expire(key, value, ttl)
+      multi do
+        set(key, value)
+        expire(key, ttl)
+      end
+    end
+
+    def mset(*args)
+      if args.size == 1
+        deprecated("mset with a hash", :mapped_mset, caller[0])
+        mapped_mset(args[0])
+      else
+        call_command(args.unshift(:mset))
+      end
+    end
+
+    def mapped_mset(hash)
+      mset(*hash.to_a.flatten)
+    end
+
+    def msetnx(*args)
+      if args.size == 1
+        deprecated("msetnx with a hash", :mapped_msetnx, caller[0])
+        mapped_msetnx(args[0])
+      else
+        call_command(args.unshift(:msetnx))
+      end
+    end
+
+    def mapped_msetnx(hash)
+      msetnx(*hash.to_a.flatten)
+    end
+
+    # Similar to memcache.rb's #get_multi, returns a hash mapping
+    # keys to values.
+    def mapped_mget(*keys)
+      result = {}
+      mget(*keys).each do |value|
+        key = keys.shift
+        result.merge!(key => value) unless value.nil?
+      end
+      result
+    end
+
+    def sort(key, options = {})
+      cmd = ["SORT"]
+      cmd << key
+      cmd << "BY #{options[:by]}" if options[:by]
+      cmd << "GET #{[options[:get]].flatten * ' GET '}" if options[:get]
+      cmd << "#{options[:order]}" if options[:order]
+      cmd << "LIMIT #{options[:limit].join(' ')}" if options[:limit]
+      cmd << "STORE #{options[:store]}" if options[:store]
+      call_command(cmd)
+    end
+
+    def incr(key, increment = nil)
+      call_command(increment ? ["incrby",key,increment] : ["incr",key])
+    end
+
+    def decr(key,decrement = nil)
+      call_command(decrement ? ["decrby",key,decrement] : ["decr",key])
+    end
+
+    # Ruby defines a now deprecated type method so we need to override it here
+    # since it will never hit method_missing
+    def type(key)
+      call_command(['type', key])
+    end
+
+    def quit
+      call_command(['quit'])
+    rescue Errno::ECONNRESET
+    end
+
+    def pipelined(&block)
+      pipeline = Pipeline.new self
+      yield pipeline
+      pipeline.execute
+    end
+
+    def exec
+      # Need to override Kernel#exec.
+      call_command([:exec])
+    end
+
+    def multi(&block)
+      result = call_command [:multi]
+
+      return result unless block_given?
+
+      begin
+        yield(self)
+        exec
+      rescue Exception => e
+        discard
+        raise e
+      end
+    end
+
+    def subscribe(*classes)
+      # Sanity check, as our API is a bit tricky. You MUST call
+      # the top-level subscribe with a block, but you can NOT call
+      # the nested subscribe calls with a block, as all the messages
+      # are processed by the top level call.
+      if @pubsub == false and !block_given?
+        raise "You must pass a block to the top level subscribe call"
+      elsif @pubsub == true and block_given?
+        raise "Can't pass a block to nested subscribe calls"
+      elsif @pubsub == true
+        # This is a nested subscribe call without a block given.
+        # We just need to send the subscribe command and return asap.
+        call_command [:subscribe,*classes]
+        return true
+      end
+      @pubsub = true
+      call_command [:subscribe,*classes]
+      while true
+        r = read_reply
+        msg = {:type => r[0], :class => r[1], :data => r[2]}
+        yield(msg)
+        break if msg[:type] == "unsubscribe" and r[2] == 0
+      end
+      @pubsub = false
+    end
+
+    def unsubscribe(*classes)
+      call_command [:unsubscribe,*classes]
+      return true
+    end
+
+  protected
+
+    def call_command(argv)
+      log(argv.inspect, :debug)
+
+      # this wrapper to raw_call_command handle reconnection on socket
+      # error. We try to reconnect just one time, otherwise let the error
+      # araise.
+      connect_to_server if !@sock
+
+      begin
+        raw_call_command(argv.dup)
+      rescue Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED
+        @sock.close rescue nil
+        @sock = nil
+        connect_to_server
+        raw_call_command(argv.dup)
+      end
+    end
+
+    def server
+      "#{@host}:#{@port}"
     end
 
     def connect_to(host, port, timeout=nil)
       # We support connect() timeout only if system_timer is availabe
       # or if we are running against Ruby >= 1.9
       # Timeout reading from the socket instead will be supported anyway.
-      if @timeout != 0 and RedisTimer
+      if @timeout != 0 and Timer
         begin
           sock = TCPSocket.new(host, port)
         rescue Timeout::Error
@@ -180,32 +347,20 @@ module RedisRb
           sock.setsockopt Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, optval
         rescue Exception => ex
           # Solaris, for one, does not like/support socket timeouts.
-          @logger.info "Unable to use raw socket timeouts: #{ex.class.name}: #{ex.message}" if @logger
+          log("Unable to use raw socket timeouts: #{ex.class.name}: #{ex.message}")
         end
       end
       sock
     end
 
-    def method_missing(*argv)
-      call_command(argv)
+    def connect_to_server
+      @sock = connect_to(@host, @port, @timeout == 0 ? nil : @timeout)
+      call_command(["auth",@password]) if @password
+      call_command(["select",@db]) unless @db == 0
     end
 
-    def call_command(argv)
-      @logger.debug { argv.inspect } if @logger
-
-      # this wrapper to raw_call_command handle reconnection on socket
-      # error. We try to reconnect just one time, otherwise let the error
-      # araise.
-      connect_to_server if !@sock
-
-      begin
-        raw_call_command(argv.dup)
-      rescue Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED
-        @sock.close rescue nil
-        @sock = nil
-        connect_to_server
-        raw_call_command(argv.dup)
-      end
+    def method_missing(*argv)
+      call_command(argv)
     end
 
     def raw_call_command(argvp)
@@ -231,8 +386,11 @@ module RedisRb
         command = ""
         argvv.each do |argv|
           bulk = nil
-          argv[0] = argv[0].to_s.downcase
-          argv[0] = ALIASES[argv[0]] if ALIASES[argv[0]]
+          argv[0] = argv[0].to_s
+          if ALIASES[argv[0]]
+            deprecated(argv[0], ALIASES[argv[0]], caller[4])
+            argv[0] = ALIASES[argv[0]]
+          end
           raise "#{argv[0]} command is disabled" if DISABLED_COMMANDS[argv[0]]
           if BULK_COMMANDS[argv[0]] and argv.length > 1
             bulk = argv[-1].to_s
@@ -242,8 +400,13 @@ module RedisRb
           command << "#{bulk}\r\n" if bulk
         end
       end
+      # When in Pub/Sub mode we don't read replies synchronously.
+      if @pubsub
+        @sock.write(command)
+        return true
+      end
+      # The normal command execution is reading and processing the reply.
       results = maybe_lock { process_command(command, argvv) }
-
       return pipeline ? results : results[0]
     end
 
@@ -263,89 +426,6 @@ module RedisRb
       end
     end
 
-    def select(*args)
-      raise "SELECT not allowed, use the :db option when creating the object"
-    end
-
-    def [](key)
-      self.get(key)
-    end
-
-    def []=(key,value)
-      set(key,value)
-    end
-
-    def set(key, value, expiry=nil)
-      s = call_command([:set, key, value]) == OK
-      expire(key, expiry) if s && expiry
-      s
-    end
-
-    def mset(*args)
-      hsh = args.pop if Hash === args.last
-      if hsh
-        call_command(hsh.to_a.flatten.unshift(:mset))
-      else
-        call_command(args.unshift(:mset))
-      end
-    end
-
-    def msetnx(*args)
-      hsh = args.pop if Hash === args.last
-      if hsh
-        call_command(hsh.to_a.flatten.unshift(:msetnx))
-      else
-        call_command(args.unshift(:msetnx))
-      end
-    end
-
-    def sort(key, options = {})
-      cmd = ["SORT"]
-      cmd << key
-      cmd << "BY #{options[:by]}" if options[:by]
-      cmd << "GET #{[options[:get]].flatten * ' GET '}" if options[:get]
-      cmd << "#{options[:order]}" if options[:order]
-      cmd << "LIMIT #{options[:limit].join(' ')}" if options[:limit]
-      cmd << "STORE #{options[:store]}" if options[:store]
-      call_command(cmd)
-    end
-
-    def incr(key, increment = nil)
-      call_command(increment ? ["incrby",key,increment] : ["incr",key])
-    end
-
-    def decr(key,decrement = nil)
-      call_command(decrement ? ["decrby",key,decrement] : ["decr",key])
-    end
-
-    # Similar to memcache.rb's #get_multi, returns a hash mapping
-    # keys to values.
-    def mapped_mget(*keys)
-      result = {}
-      mget(*keys).each do |value|
-        key = keys.shift
-        result.merge!(key => value) unless value.nil?
-      end
-      result
-    end
-
-    # Ruby defines a now deprecated type method so we need to override it here
-    # since it will never hit method_missing
-    def type(key)
-      call_command(['type', key])
-    end
-
-    def quit
-      call_command(['quit'])
-    rescue Errno::ECONNRESET
-    end
-
-    def pipelined(&block)
-      pipeline = Pipeline.new self
-      yield pipeline
-      pipeline.execute
-    end
-
     def read_reply
       # We read the first byte using read() mainly because gets() is
       # immune to raw socket timeouts.
@@ -387,28 +467,16 @@ module RedisRb
       end
     end
 
-    def exec
-      # Need to override Kernel#exec.
-      call_command([:exec])
+    def get_size(string)
+      string.respond_to?(:bytesize) ? string.bytesize : string.size
     end
 
-    def multi(&block)
-      result = call_command [:multi]
-
-      return result unless block_given?
-
-      begin
-        yield(self)
-        exec
-      rescue Exception => e
-        discard
-        raise e
-      end
+    def log(str, level = :info)
+      @logger.send(level, str.to_s) if @logger
     end
 
-    private
-      def get_size(string)
-        string.respond_to?(:bytesize) ? string.bytesize : string.size
-      end
+    def deprecated(old, new, trace = caller[0])
+      $stderr.puts "\nRedis: The method #{old} is deprecated. Use #{new} instead (in #{trace})"
+    end
   end
 end