attr_bucket 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,7 +1,156 @@
 = attr_bucket
 
-This is probably a horrible idea.
+Sometimes you're tempted to use STI in your Rails app, but your STI classes
+don't share all of the same attributes. So, you're left with two choices:
 
-== Copyright
+  1. Add _all_ of the columns your descendant classes will need.
+  2. Remember that this occurrence is a telltale sign that STI is the wrong
+     design pattern to be using...
+
+<b>OR IS IT?</b> Yes, it is. Probably.
+
+But wait! I present you with a third option:
+
+  3. Give your model a bucket. So it can hold all its extra attributes.
+
+Hoo boy. This is probably a horrible idea.
+
+== Usage
+
+Let's say we have a table containing animals. Animals have some universal traits,
+such as a number of legs. We want to be able to search on those. But they also have
+some specific traits that we'd like to display on the animal's detail page. We
+don't (and this part is important) care about searching on these traits, we just want
+to display them. OK, let's have at it:
+
+  class Animal < ActiveRecord::Base
+    # t.string  :type
+    # t.string  :name
+    # t.integer :number_of_legs
+    # t.boolean :can_fly
+    # t.boolean :is_cuddly
+    # t.text    :unique_traits
+  end
+
+We'll only track one unique attribute for birds, for now. This will be a string,
+because strings are the default type for attributes in a bucket.
+
+  class Bird < Animal
+    attr_bucket :unique_traits => :group_name # "Murder" of crows, for instance
+  end
+
+We might want to know "fresh" or "salt" for fish, (and whether they go best with
+rice or asparagus). These will also be strings.
+
+  class Fish < Animal
+    attr_bucket :unique_traits => [:best_served_with, :water_type]
+  end
+
+Now, we have a special animal that we want to add some non-string attributes to,
+so we'll define our bucket with a hash, instead:
+
+  class Lolrus < Animal
+    # Yes, this actually works. It's an alias. Come on, I had to.
+    i_has_a_bucket :unique_traits => {
+      :in_possession_of_bucket => :boolean, # Has it been stolen yet?
+      :tusk_length_in_inches   => :integer,
+      :also_known_as           => :string
+    }
+  end
+
+Now, we can create some animals. Let's start with a crow.
+
+  crow = Bird.create(
+    :name => 'Crow',
+    :number_of_legs => 2,
+    :can_fly => true,
+    :is_cuddly => false,
+    :group_name => 'Murder'
+  )
+  => #<Bird id: 1, type: "Bird", name: "Crow", ...>
+
+Looks about like we'd expect. Now we can retrieve our bucketed attributes by name,
+without worrying about the bucket they're in.
+
+  crow.group_name
+  => "Murder"
+
+Let's create a fish of some kind. How about a salmon?
+
+  salmon = Fish.create(
+    :name => 'Salmon',
+    :number_of_legs => 0,
+    :can_fly => false,
+    :is_cuddly => false,
+    :water_type => 'fresh',
+    :best_served_with => 'Pan-fried asparagus'
+  )
+  => #<Fish id: 3, type: "Fish", name: "Salmon", ...>
+
+As before, we can retrieve the bucketed attribute:
+
+  salmon.best_served_with
+  => "Pan-fried asparagus"
+
+We can also change the attribute using a standard attribute writer, so this works just
+fine with Rails forms.
+
+  salmon.best_served_with = 'A light red wine'
+  => "A light red wine"
+  salmon.save
+  => true
+
+Let's pull it back out of the database and make sure everything looks right:
+
+  fish = Fish.find 3
+  => #<Fish id: 3, type: "Fish", name: "Salmon", ...>
+  fish == salmon
+  => true
+
+And it maintained our updated attribute.
+
+  fish.best_served_with
+  => "A light red wine"
+
+Now let's try an animal with some typecasting -- I'll create using string values for
+the bucketed attributes since that's what a Rails form would send:
+
+  lolrus = Lolrus.create(
+    :name => 'The LOLRUS',
+    :number_of_legs => 0, # Do flippers count as legs?
+    :can_fly => false,
+    :is_cuddly => true,
+    :also_known_as => 'The Holder of the Bucket',
+    :in_possession_of_bucket => 't',
+    :tusk_length_in_inches => '6'
+  )
+  => #<Lolrus id: 5, type: "Lolrus", name: "The LOLRUS", ...>
+
+Let's make sure the attributes got cast to the proper type:
+
+  lolrus.tusk_length_in_inches
+  => 6
+  lolrus.in_possession_of_bucket
+  => true
+
+That lolrus looks to be in fine shape, indeed.
+
+== Caveats
+
+This whole thing's a caveat, really. If you're looking to do this, be absolutely,
+positively sure that you really want to bucket your attributes rather than inherit
+from an abstract class or something a bit, well, more sane.
+
+attr_bucket isn't for you if:
+
+  * You ever intend to search against your custom attributes
+  * You plan to instantiate tons of records at a time (the serialization overhead
+    will hurt -- though it'll hurt less with psych)
+  * You want to get invited to all the cool software engineer parties
+
+All that caveat-ing aside, give it a try, and let me know if you find a particularly
+clever use case!
+
+== Copyright (or blame, depending on how you look at it)
 
 Copyright (c) 2011 {Ernie Miller}[http://metautonomo.us]. See LICENSE for details.

data/attr_bucket.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Ernie Miller"]
   s.email       = ["ernie@metautonomo.us"]
   s.homepage    = "http://metautonomo.us"
-  s.summary     = %q{This is probably a horrible idea.}
-  s.description = %q{A really, really, horrible idea.}
+  s.summary     = %q{Your model can has a bucket (for its attributes).}
+  s.description = %q{Store a few extra (non-searchable) attributes away in a bucket. This is probably a horrible idea, but try it anyway.}
 
   s.add_runtime_dependency(%q<activerecord>, ["~> 3.0.0"])
 

data/lib/attr_bucket.rb

@@ -12,20 +12,20 @@ module AttrBucket
     read_attribute(name)
   end
 
-  def explicitly_type_cast(value, type)
+  def explicitly_type_cast(value, type, column_class)
     return nil if value.nil?
     case type
       when :string    then value.to_s
       when :text      then value.to_s
       when :integer   then value.to_i rescue value ? 1 : 0
       when :float     then value.to_f
-      when :decimal   then self.class.value_to_decimal(value)
-      when :datetime  then self.class.string_to_time(value)
-      when :timestamp then self.class.string_to_time(value)
-      when :time      then self.class.string_to_dummy_time(value)
-      when :date      then self.class.string_to_date(value)
-      when :binary    then self.class.binary_to_string(value)
-      when :boolean   then self.class.value_to_boolean(value)
+      when :decimal   then column_class.value_to_decimal(value)
+      when :datetime  then column_class.string_to_time(value)
+      when :timestamp then column_class.string_to_time(value)
+      when :time      then column_class.string_to_dummy_time(value)
+      when :date      then column_class.string_to_date(value)
+      when :binary    then column_class.binary_to_string(value)
+      when :boolean   then column_class.value_to_boolean(value)
       else value
     end
   end
@@ -35,33 +35,40 @@ module AttrBucket
 
     def attr_bucket(opts = {})
       opts.map do |bucket_name, attrs|
+        bucket_column = self.columns_hash[bucket_name.to_s]
+        unless bucket_column.type == :text
+          raise ArgumentError,
+                "#{bucket_name} is a #{bucket_column.type} column, not text"
+        end
         serialize bucket_name, Hash
 
         if attrs.is_a?(Hash)
           attrs.map do|attr_name, attr_type|
             define_bucket_reader bucket_name, attr_name
-            define_bucket_writer bucket_name, attr_name, attr_type
+            define_bucket_writer bucket_name, attr_name, attr_type, bucket_column.class
           end
         else
           Array.wrap(attrs).each do |attr_name|
             define_bucket_reader bucket_name, attr_name
-            define_bucket_writer bucket_name, attr_name, :string
+            define_bucket_writer bucket_name, attr_name, :string, bucket_column.class
           end
         end
       end
     end
 
+    alias :i_has_a_bucket :attr_bucket
+
     def define_bucket_reader(bucket_name, attr_name)
       define_method attr_name do
         get_attr_bucket(bucket_name)[attr_name]
       end unless method_defined? attr_name
     end
 
-    def define_bucket_writer(bucket_name, attr_name, attr_type)
+    def define_bucket_writer(bucket_name, attr_name, attr_type, column_class)
       define_method "#{attr_name}=" do |val|
         # TODO: Make this more resilient/granular for multiple bucketed changes
         send("#{bucket_name}_will_change!")
-        get_attr_bucket(bucket_name)[attr_name] = explicitly_type_cast(val, attr_type)
+        get_attr_bucket(bucket_name)[attr_name] = explicitly_type_cast(val, attr_type, column_class)
       end unless method_defined? "#{attr_name}="
     end
   end

data/lib/attr_bucket/version.rb

@@ -1,3 +1,3 @@
 module AttrBucket
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Ernie Miller
@@ -32,7 +32,7 @@ dependencies:
         version: 3.0.0
   type: :runtime
   version_requirements: *id001
-description: A really, really, horrible idea.
+description: Store a few extra (non-searchable) attributes away in a bucket. This is probably a horrible idea, but try it anyway.
 email: 
 - ernie@metautonomo.us
 executables: []
@@ -81,6 +81,6 @@ rubyforge_project: attr_bucket
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: This is probably a horrible idea.
+summary: Your model can has a bucket (for its attributes).
 test_files: []