stash 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Tony Arcieri
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,92 @@
+Stash
+=====
+
+*"The sloping companion I cast down the ash, yanked on my tunic and dangled my stash"*
+
+Stash provides Ruby-like classes for interacting with data structures servers.
+Presently the only such server supported is Redis, however support is planned
+for Membase, Memcache, and possibly Kestrel.
+
+Initializing Stash
+------------------
+
+Stash supports multiple connections which are initialized through the
+stash Stash.setup command. Stash operates primarily through the default
+connection:
+
+    Stash.setup :default, :adapter => :redis, :host => 'localhost'
+    
+This will connect to the Redis server listening on localhost. Stash.setup
+takes an options hash with the following parameters:
+
+- **adapter**: must be "redis" (*mandatory*)
+- **host**: hostname or IP address of the Redis server (*mandatory*)
+- **port**: port of the Redis server (*optional, default 6379*)
+- **namespace**: Redis namspace to use (*optional, default global namespace*)
+- **password**: password to the Redis server (*optional*)
+
+Strings
+-------
+
+The core type exposed by Stash is a string. You can store a string in the
+default Stash using:
+
+    Stash[:foobar] = "mystring"
+    
+This string can be retrieved as easily as:
+
+    Stash[:foobar]
+    
+And deleted with:
+
+    Stash.delete :foobar
+    
+Lists
+-----
+
+Stash supports a mostly ordered list type. You can retrieve a list with:
+
+    Stash::List[:baz]
+    
+Stash Lists support most of the methods you'd expect on the Ruby Array type.
+They are enumerable and support all of Ruby's Enumerable methods.
+
+You can push elements onto the list with:
+
+    Stash::List[:baz] << 'asdf'
+    
+And pop them with:
+
+    Stash::List[:baz].pop
+    
+Lists can be converted to arrays with:
+
+    Stash::List[:baz].to_a
+    
+Or iterated with:
+
+    Stash::List[:baz].each { |elem| ... }
+    
+Stash asks you to think of lists as being somewhat loosely ordered. This 
+means that Stash will make its best effort to give you a list in order, 
+however that order may shift around depending on how the backend storage 
+system is implemented. Distributed systems may be interesting properties.
+    
+Hashes
+------
+
+Stash hashes work like Ruby hashes. You can retrieve a Stash::Hash with:
+
+    Stash::Hash[:qux]
+    
+You can set members of a Stash::Hash with:
+
+    Stash::Hash[:qux][:omgwtf] == "bbq"
+   
+or retrieve them with:
+
+    Stash::Hash[:qux][:omgwtf]
+    
+You can convert a Stash::Hash to a Ruby hash with:
+
+    Stash::Hash[:qux].to_hash

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "stash"
+    gem.summary = "Abstract interface to data structures servers"
+    gem.description = "Stash maps the facilities provided by data structures servers onto classes which mimic Ruby's built-in types"
+    gem.email = "tony@medioh.com"
+    gem.homepage = "http://github.com/tarcieri/stash"
+    gem.authors = ["Tony Arcieri"]
+    gem.add_dependency "redis", "~> 2.1.0"
+    gem.add_dependency "redis-namespace", "~> 0.10.0"
+    gem.add_development_dependency "rspec", "~> 2.1.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:rspec) do |rspec|
+  rspec.rspec_opts = %w[-fs -c -b]
+end
+
+RSpec::Core::RakeTask.new(:rspec) do |rspec|
+  rspec.rspec_opts = %w[-fs -c -b]
+  rspec.rcov = true
+end
+
+task :rspec => :check_dependencies
+task :spec  => :rspec
+
+task :default => :rspec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "stash #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/stash/class_methods.rb

@@ -0,0 +1,47 @@
+class Stash
+  # Configuration error
+  class ConfigError < StandardError; end
+  
+  module ClassMethods
+    def [](key)
+      default[key]
+    end
+    
+    def []=(key, value)
+      default[key] = value
+    end
+    
+    # Add a configuration entry to Stash
+    def setup(label, configuration)
+      @configurations ||= {}
+      @configurations[label.to_sym] = configuration
+      
+      if label == :default
+        @default = nil
+        default
+      end
+    end
+  
+    # Retrieve the default Stash configuration
+    def default
+      @default ||= begin
+        raise ConfigError, "please configure me with Stash.setup" unless @configurations
+        raise ConfigError, "no default configuration" unless @configurations[:default]
+        new(@configurations[:default])
+      end
+    end
+    
+    # Retrieve a particular Stash configuration
+    def configuration(key)
+      @configurations[key.to_sym]
+    end
+    
+    # Delete a key from the Stash
+    def delete(key)
+      default.delete(key)
+      true
+    end
+  end
+  
+  extend ClassMethods
+end

data/lib/stash/hash.rb

@@ -0,0 +1,61 @@
+# Stash::Hashes are remotely located lookup tables
+class Stash::Hash
+  include Enumerable
+  
+  def self.[](key)
+    new(key)
+  end
+  
+  def initialize(key, adapter = Stash.default.adapter)
+    @name, @adapter = key.to_s, adapter
+  end
+  
+  # Retrieve the value associated with a given key
+  def [](key)
+    @adapter.hash_get @name, key.to_s
+  end
+  
+  # Set a value in the hash
+  def []=(key, value)
+    @adapter.hash_set @name, key.to_s, value.to_s
+  end
+  
+  # Clear all elements from the hash
+  def clear
+    @adapter.delete @name
+    self
+  end
+  
+  # Delete a value from the hash
+  def delete(key)
+    @adapter.hash_delete @name, key.to_s
+  end
+  
+  # Return the length of a hash
+  def length
+    @adapter.hash_length @name
+  end
+  
+  # Is this hash empty?
+  def empty?
+    length == 0
+  end
+  
+  # Cast to a Ruby hash
+  def to_hash
+    @adapter.hash_value @name
+  end
+  
+  # Enumerate hashes
+  def each(&block)
+    to_hash.each(&block)
+  end
+  
+  # Inspect a hash
+  def inspect
+    "#<Stash::Hash[:#{@name}]: #{to_hash.inspect}>"
+  end
+  
+  # Create a string representation of a hash
+  alias_method :to_s, :inspect
+end

data/lib/stash/list.rb

@@ -0,0 +1,90 @@
+# Stash::Lists are (mostly) ordered lists stored remotely on the server
+class Stash::List
+  include Enumerable
+  
+  def self.[](key)
+    new(key)
+  end
+  
+  def initialize(key, adapter = Stash.default.adapter)
+    @key, @adapter = key.to_s, adapter
+  end
+  
+  # Cast to an array
+  def to_ary
+    @adapter.list_range @key, 0, length
+  end
+  alias_method :to_a, :to_ary
+  
+  # Get the length of a list
+  def length
+    @adapter.list_length(@key)
+  end
+  
+  # Is this list empty?
+  def empty?
+    length == 0
+  end
+  
+  # Clear all elements from the list
+  def clear
+    @adapter.delete @key
+    self
+  end
+  
+  # Push an element onto the list (i.e. right push)
+  def push(elem)
+    @adapter.list_push @key, elem.to_s, :right
+    self
+  end
+  alias_method :<<, :push
+  alias_method :rpush, :push
+  
+  # Unshift an element onto the list (i.e. left push)
+  def unshift(elem)
+    @adapter.list_push @key, elem.to_s, :left
+  end
+  alias_method :lpush, :unshift
+  
+  # Pop from a list (i.e. right pop)
+  def pop
+    @adapter.list_pop @key, :right
+  end
+  alias_method :rpop, :pop
+  
+  # Shift from a list (i.e. left pop)
+  def shift
+    @adapter.list_pop @key, :left
+  end
+  alias_method :lpop, :shift
+  
+  # Blocking shift: wait for a message to be pushed (with an optional timeout)
+  def bshift(timeout = nil)
+    @adapter.list_blocking_pop @key, :left, timeout
+  end
+  alias_method :blpop, :bshift
+  
+  # Blocking pop: wait for a message to be unshifted (with an optional timeout)
+  def bpop(timeout = nil)
+    @adapter.list_blocking_pop @key, :right, timeout
+  end
+  alias_method :brpop, :bpop
+  
+  # Iterate the list
+  def each(&block)
+    to_ary.each(&block)
+  end
+  
+  # Obtain the last element in a list
+  def last
+    to_ary[-1]
+  end
+  
+  # Inspect a list
+  def inspect
+    "#<Stash::List[:#{@key}]: #{to_ary.inspect}>"
+  end
+  
+  # Create a string representation of a list
+  alias_method :to_s, :inspect
+end

data/lib/stash/redis_adapter.rb

@@ -0,0 +1,132 @@
+require 'redis'
+require 'redis-namespace'
+
+class Stash
+  # Adapter for the Redis data structures server. 
+  # See http://code.google.com/p/redis/
+  class RedisAdapter
+    attr_reader :capabilities
+    
+    def initialize(config)
+      # Symbolize keys in config
+      config = config.inject({}) { |h, (k, v)| h[k.to_sym] = v; h }
+      
+      raise ArgumentError, "missing 'host' key" unless config[:host]
+      config[:port] ||= 6379 # Default Redis port
+      
+      redis = Redis.new config
+      redis = Redis::Namespace.new config[:namespace], :redis => redis if config[:namespace]
+      
+      @capabilities = [:string, :list, :hash]
+      
+      # Redis 2.0RC+ supports blocking pop
+      @capabilities << :bpop if redis.info['redis_version'] >= "1.3.0"
+      
+      @redis = redis
+    end
+    
+    # Set a given key within Redis
+    def []=(key, value)
+      @redis.set key.to_s, value.to_s
+    end
+    
+    # Retrieve a given key from Redis
+    def [](key)
+      case type(key)
+      when "none"   then nil
+      when "string" then Stash::String.new key, self
+      when "list"   then Stash::List.new   key, self
+      else raise "unknown Redis key type: #{key}"
+      end
+    end
+    
+    # Retrieve the type for a given key
+    def type(key)
+      @redis.type key.to_s
+    end
+    
+    # Retrieve a key as a string
+    def get(key)
+      @redis.get key.to_s
+    end
+    
+    # Delete a key
+    def delete(key)
+      @redis.del key.to_s
+    end
+    
+    # Push an element onto a list
+    def list_push(name, value, side)
+      case side
+      when :right
+        @redis.rpush name.to_s, value.to_s
+      when :left
+        @redis.lpush name.to_s, value.to_s
+      else raise ArgumentError, "left or right plztks"
+      end
+    end
+        
+    # Pop from a list
+    def list_pop(name, side)
+      case side
+      when :right
+        @redis.rpop name.to_s
+      when :left
+        @redis.lpop name.to_s
+      else raise ArgumentError, "left or right plztks"
+      end
+    end
+    
+    # Blocking pop from a list
+    def list_blocking_pop(name, side, timeout = nil)
+      timeout ||= 0
+      res = case side
+      when :left
+        @redis.blpop name, timeout
+      when :right
+        @redis.brpop name, timeout
+      else raise ArgumentError, "left or right plztks"
+      end
+      
+      return res[1] if res
+      raise Stash::TimeoutError, "request timed out"
+    end
+    
+    # Retrieve the length of a list
+    def list_length(name)
+      @redis.llen name.to_s
+    end
+    
+    # Retrieve the given range from a list
+    def list_range(name, from, to)
+      @redis.lrange name.to_s, from, to
+    end
+    
+    # Retrieve a value from a hash
+    def hash_get(name, key)
+      res = @redis.hget name.to_s, key.to_s
+      return if res == ""
+      res
+    end
+    
+    # Store a value in a hash
+    def hash_set(name, key, value)
+      @redis.hset name.to_s, key.to_s, value.to_s
+    end
+    
+    # Retrieve the contents of a hash as a Ruby hash
+    def hash_value(name)
+      @redis.hgetall name.to_s
+    end
+    
+    # Delete an entry from a hash
+    def hash_delete(name, key)
+      @redis.hdel name.to_s, key.to_s
+    end
+    
+    # Return the length of a hash
+    def hash_length(name)
+      @redis.hlen name.to_s
+    end
+  end
+end

data/lib/stash/string.rb

@@ -0,0 +1,16 @@
+# Strings are Stash's most basic type, and the only non-collection type
+# They store exactly that, a string, and nothing more
+class Stash::String
+  def initialize(key, adapter = Stash.default.adapter)
+    @adapter, @key = adapter, key.to_s
+  end
+  
+  def to_string
+    @adapter.get @key
+  end
+  alias_method :to_s, :to_string
+  
+  def inspect
+    "#<Stash::String[:#{key}]: #{to_s}>"
+  end
+end

data/lib/stash.rb

@@ -0,0 +1,43 @@
+# Stash is an abstract interface to data structures servers
+class Stash
+  attr_reader :adapter
+  
+  # Timeout when performing a blocking action, such as blocking pop
+  class TimeoutError < StandardError; end
+  
+  def initialize(config)
+    raise ArgumentError, "no adapter specified" unless config[:adapter]
+    adapter_name  = config[:adapter].to_s.split('_').map { |s| s.capitalize }.join
+    adapter_name += "Adapter"  
+    
+    begin
+      adapter_class = Stash.const_get adapter_name
+    rescue NameError
+      raise ArgumentError, "unknown adapter: #{config[:adapter]}"
+    end
+    
+    @adapter = adapter_class.new config
+  end 
+  
+  # Store an object in the Stash
+  def []=(key, value)
+    @adapter[key.to_s] = value
+  end
+  
+  # Retrieve an object from the Stash
+  def [](key)
+    @adapter[key.to_s]
+  end
+  
+  # Remove a key from the Stash
+  def delete(key)
+    @adapter.delete(key.to_s)
+    true
+  end
+end
+
+require 'stash/class_methods'
+require 'stash/redis_adapter'
+require 'stash/string'
+require 'stash/list'
+require 'stash/hash'

data/spec/hash_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Stash::Hash do
+  before :each do
+    @hash = Stash::Hash[:foobar]
+    @hash.clear
+  end
+  
+  it "clears hashes" do
+    @hash[:foo] = "a"
+    @hash[:bar] = "b"
+    @hash.clear
+    @hash.to_hash.should == {}
+  end
+  
+  it "sets and gets strings from hashes" do
+    @hash[:foo].should be_nil
+    @hash[:foo] = "42"
+    @hash[:foo].should == "42"
+  end
+  
+  it "casts to a Ruby hash" do
+    @hash.should be_empty
+    @hash['foo'] = 'a'
+    @hash['bar'] = 'b'
+    
+    @hash.to_hash.should == {'foo'=>'a', 'bar'=>'b'}
+  end
+end

data/spec/list_spec.rb

@@ -0,0 +1,65 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Stash::List do
+  before :each do
+    @list = Stash::List[:foobar]
+    @list.clear
+  end
+  
+  it "clears lists" do
+    @list << "x"
+    @list << "y"
+    @list << "z"
+    @list.clear
+    @list.to_a.should == []
+  end
+    
+  it "pushes to lists" do
+    # Normal syntax
+    @list.push "zomg"
+    
+    # Cool syntax
+    @list << "wtf"
+    
+    @list.to_a.should == ["zomg", "wtf"]
+  end
+  
+  it "unshifts to lists" do
+    @list.unshift "omfg"
+    @list.unshift "lulz"
+    
+    @list.to_a.should == ["lulz", "omfg"]
+  end
+  
+  it "pops from lists" do
+    @list << "x"
+    @list << "y"
+    @list << "z"
+    @list.pop.should == "z"
+    @list.to_a.should == ["x", "y"]
+  end
+  
+  it "shifts from lists" do
+    @list << "x"
+    @list << "y"
+    @list << "z"
+    @list.shift.should == "x"
+    @list.to_a.should == ["y", "z"]
+  end
+  
+  it "knows its length" do
+    @list.length.should == 0
+    
+    @list << "x"
+    @list << "y"
+    @list << "z"
+    @list.length.should == 3
+  end
+  
+  it "knows if it's empty" do
+    @list.should be_empty
+    
+    @list << "something"
+    @list.should_not be_empty
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift File.dirname(__FILE__)
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'stash'
+require 'rspec'
+require 'rspec/autorun'
+
+# Connect to Redis
+Stash.setup :default, :adapter   => :redis,
+                      :namespace => 'stash_test',
+                      :host      => '127.0.0.1',
+                      :port      => 6379

data/spec/string_spec.rb

@@ -0,0 +1,9 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Stash::String do
+  it "stores strings" do
+    Stash[:foobar] = "baz"
+    Stash[:foobar].should be_an_instance_of(Stash::String)
+    Stash[:foobar].to_s.should == "baz"
+  end
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification 
+name: stash
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Tony Arcieri
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-30 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: redis-namespace
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 55
+        segments: 
+        - 0
+        - 10
+        - 0
+        version: 0.10.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :development
+  version_requirements: *id003
+description: Stash maps the facilities provided by data structures servers onto classes which mimic Ruby's built-in types
+email: tony@medioh.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/stash.rb
+- lib/stash/class_methods.rb
+- lib/stash/hash.rb
+- lib/stash/list.rb
+- lib/stash/redis_adapter.rb
+- lib/stash/string.rb
+- spec/hash_spec.rb
+- spec/list_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/string_spec.rb
+has_rdoc: true
+homepage: http://github.com/tarcieri/stash
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Abstract interface to data structures servers
+test_files: 
+- spec/hash_spec.rb
+- spec/list_spec.rb
+- spec/spec_helper.rb
+- spec/string_spec.rb