doeskeyvalue 0.1.0 → 0.1.1

data/README.rdoc

@@ -12,68 +12,74 @@ Do the usual, of course:
 
 And add a gem dependency to your Gemfile:
 
-  gem "doeskeyvalue", ">=0.0.1"
-
-
-== Example (TODO: Update this with new API)
-
-To add document_fields to your ActiveRecord object, first add a text column to your class' backing table that will hold your document content. By default, do_document_fields will expect this column to be named "document", but you can override that easily.
-
-Once you've migrated that change into your model, here's a sample of hold to add document-style blob fields to your object:
-
-  class ObjectWithBlob < ActiveRecord::Base
-
-    # Declare that we are using document blobs in a particular column of this object:
-    do_document_fields
-
-    # Declare the columns we are adding to our document:
-    document_field :name, String
-    document_field :phone, String
-    document_field :age, Integer
-
-    # Declare the document fields you'd like to track with indexes:
-    document_index :name
-
-
-    # If we wanted to change the name of the column in which we store the document, we'd do this:
-    # do_document_fields :something_other_than_document. Like so:
-    
-    do_document_fields :settings
-    
-    # Changing the name of the column gives you a specifically-formatted field-definition method:
-    
-    settings_field :age
-    settings_field :sex
-    settings_field :location
-    
-    # This also provides a customized way to index:
-    
-    settings_index :location
-
-  end
-
-
-Now, you can add and remove new fields to this object within the document as simply as adding or removing declarations of "document_field".
-
-
-Once you've added any indices to your model's fields, you'll want to be sure to build your supporting index tables. We use separate tables with database-level indexing to support indexed lookups of data in your document_field attributes. Build these tables by running this rake task:
-
-  rake db:migrate:document_indexes
-
-
-Now, you can use strictly-provided finders to find your objects by their document field attributes. Considering the model we described above, you can lookup by any *indexed* field like so:
-
-  obj = ObjectWithBlob.find_by_name("Charlie")
-  => [#<ObjectWithBlob id: 412, document: {:name=>"Charlie", :phone=>"212-555-1234", :age=>34}, created_at: "2010-03-22 20:49:03", updated_at: "2010-03-22 20:49:03">]
-
-Finders are only added to document fields that are indexed. Finders also are all "find_all" lookups on equality.
-
-If you'd like to use special sub-searching within any of your document-formatted fields, you can use the hash-based search conditions. Given the "settings" document declared in the example above, we can now also do this:
-
-  obj = ObjectWithBlob.find_with_settings(:location=>"San Francisco, CA")
-  => [#<ObjectWithBlob id: 412, settings: {:age=>32, :sex=>"Female", :location=>"San Francisco, CA"}, created_at: "2010-03-22 20:49:03", updated_at: "2010-03-22 20:49:03">]
-
-It's simple.
+  gem "doeskeyvalue", ">=0.1.0"
+
+
+== Example 
+
+Quick and simple. First, add the declaration to your ActiveRecord model:
+
+  doeskeyvalue :settings
+  
+In this invocation, "settings" is the name of TEXT or BLOB field on your model's database table. Think
+of it as something you'd typically serialize, but would prefer solid accessor and finding behavior on.
+
+To add keys to your document, using the name of the field you provided, before (in this case 
+"settings"), add keys individually like so:
+
+  settings_key :uid
+  settings_key :email
+  settings_key :name
+  
+This adds a uid, email, and name field to your record. You can use these fields just like regular 
+columns on your ActiveRecord object, but they're happily stored within your TEXT/BLOB column at the
+database level. Check it out:
+
+  mod = Model.new
+  
+  mod.uid = "mccolin"
+  => "mccolin"
+  
+  mod.uid
+  => "mccolin"
+  
+You can see the serialized key-value structure at any time, as well. Just access your old filed:
+
+  mod.settings
+  => {:uid=>"mccolin"}
+  
+At this point, we have a fancy serialized Hash on our hands. What we really want to be able to do is
+search for objects of type Model that have certain values. That's possible, too. First, generate the
+necessary migration:
+
+  rails g doeskeyvalue
+  
+This creates db/migrate/XXX_create_key_value_index.rb for you. Migrate your database:
+
+  rake db:migrate
+  
+Now, you can declare keys that you'd like to be searchable within Model like so:
+
+  settings_index :uid
+  settings_index :email
+  
+Now, you've added powerful finders to your objects. As your objects are created, accessed, and updated,
+metadata in your index table will be updated that allows you to search against those objects similarly
+to how you'd perform lookups with a regular finder. Like so:
+
+  Model.find_all_by_uid(123)
+  => [#<Model:0x000001016b51a0 @settings=>{:uid=>123}>, #<Model:0x000001016b51a0 @settings=>{:uid=>123}>, ...]
+  
+  Model.find_all_with_settings(:email=>"foo@bar.com")
+  => [#<Model:0x000001016b51a0 @settings=>{:email=>"foo@bar"}>, ...]
+
+You can only run finds on keys for which you've added an index, but you can add and remove indexes as
+necessary simply by removing the index declaration from your model.
+
+Likewise, you can remove keys from any model by removing the key declaration. This allows you to add
+and remove keys from every ActiveRecord object at will, without having to build any migrations, but you
+can still reap the benefits of whatever SQL-backed relational database you've chosen for the bulk of
+your application's heavy lifting.
 
 
 == Prior Versions

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/doeskeyvalue.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{doeskeyvalue}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Awexome Labs"]

data/lib/doeskeyvalue/indexes.rb

@@ -8,7 +8,6 @@ module DoesKeyValue
   module Indexes
     
     def declare_index(key_value_column, key_name, opts={})
-      puts "DOES_KEY_VALUE: Index declared: #{key_value_column}, #{key_name}, #{opts.inspect}"
       raise DoesKeyValue::NoColumnNameSpecified unless key_value_column
       raise DoesKeyValue::NoKeyNameSpecified unless key_name
       raise DoesKeyValue::KeyAndIndexOptionsMustBeHash unless opts.is_a?(Hash)

data/lib/doeskeyvalue/keys.rb

@@ -7,7 +7,6 @@ module DoesKeyValue
   module Keys
     
     def declare_key(key_value_column, key_name, opts={})
-      puts "DOES_KEY_VALUE: Key declared: #{key_value_column}, #{key_name}, #{opts.inspect}"
       raise DoesKeyValue::NoColumnNameSpecified unless key_value_column
       raise DoesKeyValue::NoKeyNameSpecified unless key_name
       raise DoesKeyValue::KeyAndIndexOptionsMustBeHash unless opts.is_a?(Hash)
@@ -15,18 +14,14 @@ module DoesKeyValue
       # Define accessors for the key column in the AR class:
       class_eval <<-EOS
         def #{key_name}
-          puts "DOES_KEY_VALUE: Accessor for `#{key_name}` invoked"
           return (self.send(:#{key_value_column}) || Hash.new)[:#{key_name}]
         end
-        puts "DOES_KEY_VALUE: Key accessor `#{key_name}` declared"
       
         def #{key_name}=(value)
-          puts "DOES_KEY_VALUE: Setter for `#{key_name}` invoked"
           key_set = self.send(:#{key_value_column}) || Hash.new
           key_set[:#{key_name}] = value
           self.send("#{key_value_column}=", key_set)
         end
-        puts "DOES_KEY_VALUE: Key manipulator `#{key_name}=` declared"
       EOS
     
       # Check for opts[:index=>true] and if present, call declare_index

data/lib/doeskeyvalue.rb

@@ -47,7 +47,6 @@ module ActiveRecord
     # Call this method within your class to establish key-value behavior and prep
     # the internal structure that will hold the blob
     def self.doeskeyvalue(column, opts={})
-      puts "DOES_KEY_VALUE: Turned on for AR Column:#{column}"
       self.instance_eval do
         extend DoesKeyValue::Keys
         extend DoesKeyValue::Indexes
@@ -64,18 +63,15 @@ module ActiveRecord
       
       instance_eval <<-EOS
         def #{@@key_value_column}_key(key_name, opts={})
-          puts "DOES_KEY_VALUE: Inside defined method #{@@key_value_column}_key"
           key_name = key_name.to_sym
           declare_key(@@key_value_column, key_name, opts)
         end
         
         def #{@@key_value_column}_index(key_name, opts={})
-          puts "DOES_KEY_VALUE: Inside defined method #{@@key_value_column}_index"
           key_name = key_name.to_sym
           declare_index(@@key_value_column, key_name, opts)
         end
       EOS
-      puts "DOES_KEY_VALUE: key and index methods declared"
     end
     
     

metadata

@@ -2,7 +2,7 @@
 name: doeskeyvalue
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Awexome Labs
@@ -73,7 +73,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -2545379118669446342
+      hash: 136860461958198637
       segments: 
       - 0
       version: "0"