riak-shim 0.0.12 → 1.0.0

data/.gitignore

@@ -10,3 +10,6 @@ pkg
 spec/reports
 tmp
 vendor/bundle
+.yardoc
+_yardoc
+doc/

data/FUTURE_WORK.md

@@ -0,0 +1,28 @@
+
+## The future - mkb
+
+Riak-shim will follow [semantic versioning](http://semver.org) as best I can
+manage.
+
+My plan is to keep tweaking riak-shim to suit my own needs for two internal
+projects I am working on.  The first of those goes into production  shortly,
+so I am declaring a 1.0 release.  From here on out, minor version releases
+might introduce new functionality, but won't break what is already here.
+
+For the past few weeks riak-shim has been fairly stable and hasn't needed
+significant changes.  I am hopeful that we can avoid incompatable updates for
+a while.
+
+The area most likely to change is the handling of secondary indexes since I am
+unhappy with the current interface.
+
+## TODOS
+
+- Examples directory
+- Keep working on docs
+- Keep expanding tests
+- find less horrible way to deal with index names
+- find less horrible way to deal with key accessor
+- nice error message when can't connect to db
+
+

data/Gemfile

@@ -6,3 +6,9 @@ platforms :jruby do
   gem 'json-jruby'
 end
 
+platforms :mri_19 do
+  gem 'guard-yard'
+  gem 'yard'
+  gem 'redcarpet'
+end
+

data/Guardfile

@@ -1,7 +1,18 @@
-guard 'rspec', :version => 2, :cli => "--color --format nested" do
-  watch(%r{^spec/(.+)_spec\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
-  watch(%r{^spec/support/*})      { 'spec' }
-  watch(%r{^lib/(.+)\.rb$})       { 'spec' }
-  watch('spec/spec_helper.rb')    { "spec" }
+
+group :rspec do
+  guard 'rspec', :version => 2, :cli => "--color --format nested" do
+    watch(%r{^spec/(.+)_spec\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+    watch(%r{^spec/support/*})      { 'spec' }
+    watch(%r{^lib/(.+)\.rb$})       { 'spec' }
+    watch('spec/spec_helper.rb')    { "spec" }
+  end
 end
 
+group :yard do
+  guard 'yard', :port => '8088' do
+    watch(%r{lib/.+\.rb})
+    watch(%r{README.md})
+    watch(%r{FUTURE_WORK.md})
+    watch(%r{LICENSE})
+  end
+end

data/README.md

@@ -1,10 +1,11 @@
 # Riak Shim
 
-A teeny shim between your code and the riak-client gem.  Reads database configuration
-out of config/database.yml and derives bucket names from your class names and an
-appropriate prefix.
+A teeny shim between your code and the riak-client gem.  Reads database
+configuration out of config/database.yml and derives bucket names from your
+class names and an appropriate prefix.
 
-Riak is a database from the good people at Basho.  Check it out:  http://basho.com/products/riak-overview/
+Riak is a database from the good people at Basho.  Check it out:
+http://basho.com/products/riak-overview/
 
 [![Build Status](https://secure.travis-ci.org/mkb/riak-shim.png?branch=master)](http://travis-ci.org/mkb/riak-shim) [![Dependency Status](https://gemnasium.com/mkb/riak-shim.png)](https://gemnasium.com/mkb/riak-shim) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/mkb/riak-shim)
 
@@ -35,10 +36,14 @@ Create a config/database.yml containing the details of your Riak setup like so:
       <<: *default
       bucket_prefix: myapp_test_
 
+    production:
+      <<: *default
+      bucket_prefix: myapp_production_
+
 `bucket_prefix` will be prefixed to each bucket name, allowing you to point
-multiple applications (or multiple copies of the same application) at a
-single Riak install. During development, this prevents you from stepping on
-your own toes.
+multiple applications (or multiple copies of the same application) at a single
+Riak install. During development, this prevents you from stepping on your own
+toes.
 
 ## Converting a model to use Riak
 
@@ -52,7 +57,7 @@ Then, write a #to_hash method which returns a hash representing your object
 
     def to_hash
       # Return hashified version of your class
-      { 'foo' => self.foo, 'bar' => self.bar }
+      { 'foo' => @foo, 'bar' => @bar }
     end
 
 You'll use Class#from_hash to create an instance from the hash which was
@@ -70,15 +75,16 @@ You can now save instances of your class by calling `#save` and later retrieve
 them from Riak by calling `.for_key`:
 
     an_instance.save
+    key = an_instance.key
     retrieved_copy = YourClass.for_key(key)
 
 ### Secondary indexes
 
 Secondary indexes in Riak allow you to query based on the contents of a
-particular field.  If you'd like to look up your data by the contents
-of fields, define `#fields_to_index` and return the names of
-any fields you wish to query on.  When you #save an instance of YourClass,
-riak-shim will populate a secondary index for that field.
+particular field.  If you'd like to look up your data by the contents of
+fields, define `#fields_to_index` and return the names of any fields you wish
+to query on.  When you #save an instance of YourClass, riak-shim will populate
+a secondary index for that field.
 
     def fields_to_index
       # Return an Array of hash keys you would like placed into a secondary index.
@@ -88,7 +94,7 @@ riak-shim will populate a secondary index for that field.
 The `for_index` method retrieves all records whose value for the given index
 matches:
 
-    YourClass.for_index(index_name, value)
+    YourClass.for_index('foo_bin', 'some foo')
 
 ...where `index_name` is what you defined in `fields_to_index` plus the suffix
 "_bin" .
@@ -100,15 +106,13 @@ Return value is an Array of instances of your class matching the query.
 
 ## Contributing
 
+For a look at what work is needed (at least according to me), see
+[FUTURE_WORK.md](https://github.com/mkb/riak-shim/blob/master/FUTURE_WORK.md)
+
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
-## TODOS
-
-- Examples directory
-- Keep expanding tests
-- find less horrible way to deal with index names
 

data/lib/riak-shim/persistable.rb

@@ -1,24 +1,34 @@
+
 module Riak
   module Shim
+
+    # Provides basic persistence features
+    # @attr [String] the unique key for storing the object in Riak
     module Persistable
       attr_writer :key
 
+      # @return [String] the unique key for storing the object in Riak
       def key
         @key ||= self.class.gen_key
       end
 
+      # @return [Riak::Bucket] your app's Riak bucket for this class
       def bucket
         return self.class.store.bucket(bucket_name)
       end
 
+      # @return [String] name of the Riak bucket generated from the class name and your configuration
       def bucket_name
         self.class.bucket_name
       end
 
+      # @return [Riak::Shim::Store] the Riak cluster you are connected to
       def store
         self.class.store
       end
 
+      # Persist this object into Riak
+      # @return [Persistable] self
       def save
         doc = bucket.get_or_new(key)
         doc.data = to_hash
@@ -27,49 +37,43 @@ module Riak
         self
       end
 
+      # Remove this object from Riak
+      # @return [Persistable] self
       def destroy
         bucket.delete(key)
-      end
-
-      def set_indexes(indexes)
-        indexes.clear
-        if self.respond_to?(:fields_to_index)
-          fields_to_index.each do |field|
-            index_name = "#{field}_bin"
-            index_value = send(field)
-            indexes[index_name] << index_value
-          end
-        end
+        self
       end
 
       module ClassMethods
+        # *WARNING:* This is very slow and is intended only for your tests,
+        # not for production use.
+        #
+        # Remove all instances of this class from Riak.
         def delete_all
           bucket.keys.each do |key|
             bucket.delete(key)
           end
         end
 
+        # @return [Riak::Shim::Store] the store you are connected to
         def store
           @store ||= Store.new
         end
 
+        # @return [String] name of the Riak bucket generated from the class
+        #   name and your configuration
         def bucket_name
           myclass = de_camel(self.to_s)
           "#{store.bucket_prefix}#{myclass}"
         end
 
-        def de_camel(classname)
-          classname.gsub(/::/, '__').
-            gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-            gsub(/([a-z\d])([A-Z])/,'\1_\2').
-            tr("-", "_").
-            downcase
-        end
-
+        # @return [Riak::Bucket] your app's Riak bucket for this class
         def bucket
           return store.bucket(bucket_name)
         end
 
+        # Look up an instance of your class
+        # @return [Persistable, #nil] an instance corresponding to key
         def for_key(key)
           begin
             raw = bucket.get(key)
@@ -82,26 +86,63 @@ module Riak
           end
         end
 
+        # @return [Array<Persistable>] any instances of your class whose
+        #   indexed field matches value
+        #
+        # Locate instances by secondary index.
+        #
+        # *NOTE:* This interface is ugly as sin, so expect it to change in a future release.
         def for_index(index, value)
           bucket.get_index(index, value).map do |key|
             for_key(key)
           end
         end
 
+        # @return [String] a UUID which we will use as our key
         def gen_key
           UUIDTools::UUID.random_create.to_s
         end
 
+        # @return [Integer] the number of instances of your class stored in
+        #   Riak
+        #
+        # *WARNING:* This is very slow and is intended only for your tests,
+        # not for production use.
+        #
+        # Counts instances in the database which really means items in the
+        # bucket.
         def count
           counter = 0
           bucket.keys {|keys| counter += keys.count }
           return counter
         end
+
+        protected
+        def de_camel(classname)
+          classname.gsub(/::/, '__').
+            gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+            gsub(/([a-z\d])([A-Z])/,'\1_\2').
+            tr("-", "_").
+            downcase
+        end
       end
 
+      protected
+
       def self.included(base)
         base.extend(ClassMethods)
       end
+
+      def set_indexes(indexes)
+        indexes.clear
+        if self.respond_to?(:fields_to_index)
+          fields_to_index.each do |field|
+            index_name = "#{field}_bin"
+            index_value = send(field)
+            indexes[index_name] << index_value
+          end
+        end
+      end
     end
   end
 end

data/lib/riak-shim/store.rb

@@ -3,13 +3,25 @@ require 'uuidtools'
 
 module Riak
   module Shim
+
+    # Represents a connection to a particular Riak cluster
+    # @attr [String] config_location The path to our configuration file.  Defaults to DEFAULT_CONFIG_LOCATION
+    # @attr [Riak::Client] riak The underlying Riak connection
     class Store
+
       attr_writer :config_location
       attr_writer :riak
 
+      DEFAULT_CONFIG_LOCATION = 'config/database.yml'
+
+      # Thrown when we can't find a configuration which matches the
+      # current RACK_ENV
       class NoSettingsForCurrentEnvError < StandardError; end
+
+      # Thrown when the RACK_ENV environment variable is not set
       class RackEnvNotSetError < StandardError; end
 
+      # @return [Hash] the configuration for our current environment
       def config
         env = ENV['RACK_ENV'] or raise RackEnvNotSetError.new
         @config ||= read_config[env]
@@ -17,14 +29,16 @@ module Riak
             "RACK_ENV #{ENV['RACK_ENV']} not specified in #{config_location}.")
       end
 
+      # @return [Hash] the entire config, ie the configuration for each environment
       def read_config
         YAML.load_file(config_location)
       end
 
       def config_location
-        @config_location ||= 'config/database.yml'
+        @config_location ||= DEFAULT_CONFIG_LOCATION
       end
 
+      # @return [String] the prefix we will add to the bucket name for each class
       def bucket_prefix
         return config['bucket_prefix']
       end
@@ -34,6 +48,7 @@ module Riak
             :nodes => [{:host => config['host'], :http_port => config['http_port']}])
       end
 
+      # @return [Riak::Bucket] the bucket coresponding to name
       def bucket(name)
         riak.bucket(name)
       end

data/lib/riak-shim/version.rb

@@ -1,5 +1,5 @@
 module Riak
   module Shim
-    VERSION = "0.0.12"
+    VERSION = "1.0.0"
   end
 end

data/riak-shim.gemspec

@@ -19,12 +19,12 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'excon'
   gem.add_dependency 'uuidtools', '~>2.1.3'
 
-  gem.add_development_dependency "rake"
-  gem.add_development_dependency "rspec"
-  gem.add_development_dependency "guard"
-  gem.add_development_dependency "guard-rspec"
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "awesome_print"
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'guard'
+  gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'awesome_print'
 
   if RUBY_PLATFORM.include? 'darwin'
     gem.add_development_dependency 'growl'

data/spec/persistable_spec.rb

@@ -106,11 +106,11 @@ describe 'persistable' do
 
     context 'with a model which does not need indexes' do
       it 'does not require #fields_to_index to be defined' do
-        expect { persistable.set_indexes(@indexes) }.to_not raise_error
+        expect { persistable.send(:set_indexes, @indexes) }.to_not raise_error
       end
 
       it 'clears preexisting indexes' do
-        persistable.set_indexes(@indexes)
+        persistable.send(:set_indexes, @indexes)
         @indexes.should be_empty
       end
     end
@@ -121,7 +121,7 @@ describe 'persistable' do
         indexable.foo = 1
         indexable.bar = 2
         indexable.baz = 3
-        indexable.set_indexes(@indexes)
+        indexable.send(:set_indexes, @indexes)
       end
 
       after do
@@ -147,26 +147,30 @@ describe 'persistable' do
   end
 
   describe '#de_camel' do
+    def de_camel(camelcase)
+      PersistableExample.send(:de_camel, camelcase)
+    end
+
     it 'handles a basic camel-case name' do
       DeCamel.each do |camelcase, lowered|
-        PersistableExample.de_camel(camelcase).should eq(lowered)
+        de_camel(camelcase).should eq(lowered)
       end
     end
 
     it 'handles runs of capitals appropriately' do
       DeCamelCapsRuns.each do |camelcase, lowered|
-        PersistableExample.de_camel(camelcase).should eq(lowered)
+        de_camel(camelcase).should eq(lowered)
       end
     end
 
     it 'turns module separators into slashes' do
       DeCamelWithModule.each do |camelcase, lowered|
-        PersistableExample.de_camel(camelcase).should eq(lowered)
+        de_camel(camelcase).should eq(lowered)
       end
     end
 
     it 'does not produce collisions' do
-      PersistableExample.de_camel('RiakShim').should_not eq PersistableExample.de_camel('Riak::Shim')
+      de_camel('RiakShim').should_not eq de_camel('Riak::Shim')
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riak-shim
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-21 00:00:00.000000000 Z
+date: 2012-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: riak-client
@@ -196,6 +196,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- FUTURE_WORK.md
 - Gemfile
 - Guardfile
 - LICENSE