canery 0.1.1

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Matthias Kalb, Railsmechanic
+
+MIT License
+
+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.md

@@ -0,0 +1,52 @@
+# Canery
+Canery is a simple and easy to use key/value store with several commands to store and retrieve data. As the backend uses [Sequel](https://github.com/jeremyevans/sequel/) for persistence, Canery can be used in virtually any environment where a SQL database is available. (For more information please check out the section with the available database adapters.)
+
+## Installation
+	gem install canery
+
+## Usage
+Canery provides a simple and understandable API which is a bit inspired by Redis. So everyone with a little knowledge of Redis should be able to use Canery, too. 
+
+	require 'canery'
+
+	# Create a Client interface with an in-memory SQLite database 
+	client = Canery::Client.new
+	
+	# Create a Client interface connecting to a PostgreSQL database
+	client = Canery::Client.new("postgres://username:password@host:port/database_name")
+
+	# Create a new namespace
+	store = client.tub("store")
+
+	# Set a simple value in this defined namespace
+	store.set("github", "github is awesome") # => "github"
+
+	# Get this previously set value
+	store.get("github") # => "github is awesome"
+
+	# Canery can also handle complex data types
+	store.set("demo_hash", {:first_name => "John", :last_name => "Doe"}) # => "demo_hash"
+
+	# Get this complex value
+	store.get("demo_hash") # => {:first_name => "John", :last_name => "Doe"}
+
+For more information consider the wiki. (Comming soon... I promise!)
+
+
+## Information about data types
+### Keys & Tub names
+Theoretically every string can be used as a key/tub name, from a string like "foo" to the content of a JPEG file. Even an empty string is a valid key. But for better performance, short keys should be your first choice.
+
+Please keep in mind that Canery uses strings for all keys/tub names, so any other data type will be converted to a string!
+
+### Values
+Canery makes use of Ruby's marshaling library for serializing the given values. So every data type which supports marshalling is compatible with Canery. If you want to add serialization support to your class (for example, if you want to serialize in some specific format), or if it contains objects that would otherwise not be serializable, you can implement your own serialization strategy. See [Ruby's Mashal Documentation](http://www.ruby-doc.org/core-1.9.3/Marshal.html) for more information.
+
+## License
+Copyright (c) 2012 Matthias Kalb, Railsmechanic
+
+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/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/canery.gemspec

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require File.expand_path('../lib/canery/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Railsmechanic"]
+  gem.email         = ["info@railsmechanic.de"]
+  gem.description   = %q{A simple but handy key/value store which is able to use a bunch of SQL databases as its backend.}
+  gem.summary       = %q{Canery is a simple and easy to use key/value store with several commands to store and retrieve data. Because it uses a SQL database for storing the data, it can be used in many environments.}
+  gem.homepage      = "https://github.com/railsmechanic/canery"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "canery"
+  gem.require_paths = ["lib"]
+  gem.version       = Canery::VERSION
+  
+  # dependencies
+  gem.add_dependency "sequel", "~> 3.38.0"
+  
+  # development dependencies
+  gem.add_development_dependency "rspec", ">= 2.11.0"
+  gem.add_dependency "sqlite3-ruby", "~> 1.3.3"
+end

data/lib/canery.rb

@@ -0,0 +1,2 @@
+require "canery/client"
+require "canery/version"

data/lib/canery/backend.rb

@@ -0,0 +1,150 @@
+# encoding: utf-8
+
+require "sequel"
+require "base64"
+
+module Canery
+  
+  class Backend
+    
+    TABLE_PREFIX = "canery_"
+    
+    def initialize(connection_uri)
+      raise ArgumentError, "connection_uri must be a String or nil" unless NilClass === connection_uri || String === connection_uri
+      @connection = connection_uri.nil? ? Sequel.sqlite : Sequel.connect(connection_uri)
+      @namespace_cache = {}
+    end
+    
+    # Basic namespace methods #
+    ###########################
+    
+    def create_namespace(name)
+      connection.create_table basic_tub_name(name) do
+        String :key, :primary_key => true
+        String :value, :text => true
+      end
+    end
+    
+    def delete_namespace(name)
+      @namespace_cache.delete(basic_tub_name(name)) if @namespace_cache[basic_tub_name(name)]
+      connection.drop_table?(basic_tub_name(name)) && "OK"
+    end
+    
+    def namespace(name)
+      @namespace_cache[basic_tub_name(name)] ||= connection.dataset.select(:key, :value).from(basic_tub_name(name))
+    end
+    
+    def namespaces
+      connection.tables.select{ |name| name =~ /^#{TABLE_PREFIX}/ }.map{ |tub_name| tub_name.to_s[TABLE_PREFIX.length..-1] }
+    end
+    
+    def namespace?(name)
+      connection.table_exists?(basic_tub_name(name))
+    end
+    
+    
+    # Methods for get, set, etc. #
+    ##############################
+    
+    def get(name, key)
+      data = namespace(name).first(:key => build_key(key))
+      data.nil? ? nil : load(data[:value])
+    end
+    
+    def mget(name, keys)
+      raise ArgumentError, "keys argument must be an Array of keys" unless Array === keys
+      keys.map!{ |key| build_key(key) }
+
+      # Sort data in the order they appear in the 'keys' Array
+      namespace(name).where(:key => keys).sort_by { |element| keys.index(element[:key]) }.map {|dataset| load(dataset[:value]) }
+    end
+    
+    def set(name, key, value)
+      begin
+        namespace(name).insert(:key => build_key(key), :value => dump(value)) && build_key(key)
+      rescue Sequel::DatabaseError # raised if the key already exists, than update
+        update(name, key, value)
+      rescue
+        "ERROR"
+      end
+    end
+    
+    def mset(name, data)
+      raise ArgumentError, "data must be a Hash with keys and values" unless Hash === data
+      namespace(name).multi_insert(data.map{ |key, value| {:key => build_key(key), :value => dump(value)} }) && "OK"
+    end
+    
+    def delete(name, key)
+      namespace(name).where(:key => build_key(key)).limit(1).delete && "OK"
+    end
+    
+    def clear(name)
+      namespace(name).delete && "OK"
+    end
+    
+    def update(name, key, value)
+      namespace(name).where(:key => build_key(key)).limit(1).update(:value => dump(value)) && build_key(key)
+    end
+    
+    def has_key?(name, key)
+      !!get(name, key)
+    end
+    
+    def keys(name)
+      namespace(name).map{ |dataset| dataset[:key] }
+    end
+    
+    def values(name)
+      namespace(name).map{ |dataset| load(dataset[:value]) }
+    end
+    
+    def sort(name, order, limit)
+      data = case order.downcase
+        when :asc, 'asc'
+          namespace(name).order(Sequel.asc(:key))
+        when :desc, 'desc'
+          namespace(name).order(Sequel.desc(:key))
+        else
+          namespace(name).order(Sequel.asc(:key))
+      end
+      
+      unless limit.nil?
+        raise ArgumentError, "limit must be a positive Integer" unless Integer === limit
+        data = data.limit(limit)
+      end
+      data.map{ |dataset| dataset[:key] }
+    end
+    
+    def rename(name, old_key, new_key)
+      namespace(name).where(:key => build_key(old_key)).limit(1).update(:key => build_key(new_key)) && "OK"
+    end
+    
+    def length(name)
+      namespace(name).count
+    end
+    
+    private
+    
+    # Sequel seems to have problems with escaping, so we use Base64 encoding/decoding as a simple work around
+    def load(data)
+      Marshal.load(Base64.urlsafe_decode64(data))
+    end
+    
+    def dump(data)
+      Base64.urlsafe_encode64(Marshal.dump(data))
+    end
+    
+    def connection
+      @connection
+    end
+    
+    def build_key(key)
+      key.strip.to_s
+    end
+    
+    def basic_tub_name(name)
+      "#{TABLE_PREFIX}#{name.strip}"
+    end
+    
+  end
+end

data/lib/canery/client.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+require "canery/backend"
+require "canery/tub"
+
+module Canery
+  
+  class CaneryError < StandardError; end
+  
+  class Client
+    
+    def initialize(connection_uri = nil)
+      @backend = Backend.new(connection_uri)
+    end
+    
+    def tub(name)
+      create_tub(tub_name(name)) unless tub?(tub_name(name))
+      begin
+        @tub_cache ||= {}
+        @tub_cache[tub_name(name)] ||= Tub.new(backend, tub_name(name))
+      rescue
+        raise Canery::CaneryError, "This tub does not exist! You must create it before you can use it."
+      end
+    end
+    
+    def delete_tub(name)
+      @tub_cache.delete(tub_name(name)) if @tub_cache[tub_name(name)]
+      backend.delete_namespace(tub_name(name))
+    end
+    
+    def has_tub?(name)
+      backend.namespace?(tub_name(name))
+    end
+    alias :tub? :has_tub?
+    
+    def tubs
+      backend.namespaces
+    end
+          
+    private
+    
+    def backend
+      @backend
+    end
+    
+    def create_tub(name)
+      begin
+        backend.create_namespace(tub_name(name))
+      rescue => exception
+        raise Canery::CaneryError, exception
+      end
+    end
+    
+    def tub_name(name)
+      name.strip.to_s
+    end
+    
+  end
+end

data/lib/canery/tub.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+
+require "securerandom"
+
+module Canery
+  class Tub
+    
+    attr_reader :name
+    
+    def initialize(backend, name)
+      raise ArgumentError, "unknown backend type" unless Canery::Backend === backend
+      raise ArgumentError, "name of tub must be a String" unless String === name
+      @backend, @name = backend, name
+    end
+    
+    def get(key)
+      backend.get(name, key)
+    end
+    alias :[] :get
+    
+    def mget(keys)
+      backend.mget(name, keys)
+    end
+    
+    def set(key, value)
+      backend.set(name, key || uuid, value)
+    end
+    alias :[]= :set
+    
+    def mset(data)
+      backend.mset(name, data)
+    end
+    
+    def delete(key)
+      backend.delete(name, key)
+    end
+    
+    def clear
+      backend.clear(name)
+    end
+    
+    def has_key?(key)
+      backend.has_key?(name, key)
+    end
+    alias :key? :has_key?
+    
+    def keys
+      backend.keys(name)
+    end
+    
+    def values
+      backend.values(name)
+    end
+    
+    def sort(order, limit = nil)
+      begin
+        backend.sort(name, order, limit)
+      rescue ArgumentError
+        raise Canery::CaneryError, "limit parameter must be an Integer"
+      end
+    end
+    
+    def rename(old_key, new_key)
+      backend.rename(name, old_key, new_key)
+    end
+    
+    def length
+      backend.length(name)
+    end
+    alias :size :length
+    
+    private
+    
+    def backend
+      @backend
+    end
+    
+    def uuid
+      SecureRandom.uuid
+    end
+        
+  end
+end

data/lib/canery/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Canery
+  VERSION = "0.1.1"
+end

data/spec/canery_client_spec.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+require "canery"
+
+describe Canery::Client do
+  context "initialization" do
+    it "should not require a connection string" do
+      expect { Canery::Client.new }.not_to raise_error
+    end
+    
+    it "should hide the backend" do
+      @client = Canery::Client.new
+      expect { @client.backend }.to raise_error
+    end
+
+    it "should have no tubs initialized" do
+      @client = Canery::Client.new
+      @client.tubs.should be_empty
+    end
+    
+  end
+  
+  context "tub method" do
+    before(:each) do
+      @client = Canery::Client.new
+    end
+    
+    describe "#tub" do
+      it "should create a new tub" do
+        @client.tub("store")
+        @client.tubs.include?("store").should be_true
+      end
+
+      it "tub should be a Tub object" do
+          @client.tub("store").should be_kind_of(Canery::Tub)
+      end 
+
+      it "should use the an existing tub instead of creating a new one" do
+        @client.tub("store").should == @client.tub("store")
+      end
+    end
+    
+    describe "#delete_tub" do
+      it "should delete a specified tub" do
+        @client.tub("store")
+        @client.tubs.length.should == 1
+        @client.delete_tub("store")
+        @client.tubs.length.should == 0
+      end
+    end
+    
+    describe "#has_tub?" do
+      it "should check return true if a tub already exists" do
+        @client.tub("store")
+        @client.has_tub?("store").should be_true
+      end
+    end
+
+    describe "#tubs" do
+      it "should return a list of all tubs" do
+        @client.tub("first_store")
+        @client.tub("another_tub")
+        @client.tubs.should be_kind_of(Array)
+        @client.tubs.length.should == 2
+        @client.tubs.include?("first_store").should be_true
+        @client.tubs.include?("another_tub").should be_true
+      end
+    end
+      
+  end
+end

data/spec/canery_tub_spec.rb

@@ -0,0 +1,160 @@
+# encoding: utf-8
+
+require "spec_helper"
+require "canery"
+
+describe Canery::Tub do
+  before(:each) do
+    @client = Canery::Client.new
+  end
+  
+  context "on retrieving values" do
+    describe "#get" do
+      it "should retrieve value" do
+        store = @client.tub("store")
+        store.set("hello", "hello world")
+        store.get("hello").should == "hello world"
+      end
+      
+      it "should retrieve value using the alias method" do
+        store = @client.tub("store")
+        store.set("hello", "hello world")
+        store["hello"].should == "hello world"
+      end
+      
+      it "should return nil if value is not set" do
+        store = @client.tub("store")
+        store.get("unset_key").should be_nil
+      end
+    end
+    
+    describe "#mget" do
+      it "should retrieve multiple values at once" do
+        store = @client.tub("store")
+        store.mset(demo_hash)
+        store.mget(demo_hash.keys).each do |value|
+          demo_hash.values.should include(value)
+        end
+      end
+    end
+  end
+
+  context "on setting values" do
+    describe "#set" do
+      it "should set value and return key" do
+        store = @client.tub("store")
+        store.set("hello", "hello world").should == "hello"
+      end
+      
+      it "should set value using the alias method" do
+        store = @client.tub("store")
+        (store["hello"] = "hello world") == "hello"
+      end
+      
+      it "should overwrite an existing value" do
+        store = @client.tub("store")
+        store.set("hello", "hello world").should == "hello"
+        store.get("hello") == "hello world"
+        store.set("hello", "new hello world").should == "hello"
+        store.get("hello") == "new hello world"
+      end
+      
+      it "should automatically create an uuid key if key is nil" do
+        store = @client.tub("store")
+        uuid?(store.set(nil, "hello world")).should be_true
+      end
+    end
+    
+    describe "#mset" do
+      it "should set multiple values at once" do
+        store = @client.tub("store")
+        store.mset(demo_hash).should == "OK"
+        demo_hash.each do |key, value|
+          store.get(key).should == value
+        end
+      end
+    end
+  end
+  
+  describe "#delete" do
+    it "should delete a value" do
+      store = @client.tub("store")
+      store.set("hello", "hello world")
+      store.delete("hello").should == "OK"
+    end
+  end
+  
+  describe "#clear" do
+    it "should delete all values of a tub" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      store.size.should == demo_hash.length
+      store.clear
+      store.size.should == 0
+    end
+  end
+  
+  describe "#has_key?" do
+    it "should return true if key is present in tub" do
+      store = @client.tub("store")
+      store.set("hello", "hello world")
+      store.has_key?("hello").should be_true
+    end
+  end
+  
+  describe "#keys" do
+    it "should return all keys present in a tub" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      (store.keys & demo_hash.keys).should == demo_hash.keys
+    end
+  end
+  
+  describe "#values" do
+    it "should return all values present in a tub" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      (store.values & demo_hash.values).should == demo_hash.values
+    end
+  end
+  
+  describe "#sort" do
+    it "should sort keys in ascending order" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      (store.sort(:asc) & demo_hash.keys.sort).should == demo_hash.keys.sort
+    end
+    
+    it "should sort keys in descending order" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      data_hash = demo_hash.keys.sort{|a,b| b <=> a}
+      (store.sort(:desc) & data_hash).should == data_hash
+    end
+    
+    it "should sort keys and limit" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      (store.sort(:asc, 3) & demo_hash.keys.sort[0...3]).should == demo_hash.keys.sort[0...3]
+    end
+  end
+  
+  describe "#rename" do
+    it "should rename a key without touching the value" do
+      store = @client.tub("store")
+      store.set("hello", "hello world")
+      store.get("hello").should == "hello world"
+      store.rename("hello", "new_hello")
+      store.get("new_hello").should == "hello world"
+    end
+  end
+  
+  describe "#length" do
+    it "should return the number of elements in a tub" do
+      store = @client.tub("store")
+      store.mset(demo_hash)
+      store.length.should == demo_hash.length
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+def uuid?(value)
+  (value =~ /^[0-9a-f]{8}\-[0-9a-f]{4}\-[0-9a-f]{4}\-[0-9a-f]{4}\-[0-9a-f]{12}$/) != nil
+end
+
+def demo_hash
+  {"homer" => "Homer Simpson", "marge" => "Marge Simpson", "lisa" => "Lisa Simpson", "bart" => "Bart Simpson", "maggy" => "Maggy Simpson"}
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: canery
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Railsmechanic
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.38.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.38.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3-ruby
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.3
+description: A simple but handy key/value store which is able to use a bunch of SQL
+  databases as its backend.
+email:
+- info@railsmechanic.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- canery.gemspec
+- lib/canery.rb
+- lib/canery/backend.rb
+- lib/canery/client.rb
+- lib/canery/tub.rb
+- lib/canery/version.rb
+- spec/canery_client_spec.rb
+- spec/canery_tub_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/railsmechanic/canery
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1096333460484850874
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1096333460484850874
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Canery is a simple and easy to use key/value store with several commands
+  to store and retrieve data. Because it uses a SQL database for storing the data,
+  it can be used in many environments.
+test_files:
+- spec/canery_client_spec.rb
+- spec/canery_tub_spec.rb
+- spec/spec_helper.rb