attr_bucket 0.1.1 → 0.1.2

data/README.rdoc

@@ -3,15 +3,16 @@
 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:
 
-  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>1.</b> Add _all_ of the columns your descendant classes will need.
+
+<b>2.</b> 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.
+<b>3.</b> Give your model a bucket. So it can hold all its extra attributes.
 
 Hoo boy. This is probably a horrible idea.
 
@@ -54,10 +55,13 @@ so we'll define our bucket with a hash, instead:
     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
+      :also_known_as           => proc {|v| "aka #{v}"}
     }
   end
 
+Note the use of the proc on the value side of the hash for :also_known_as. You can
+supply any object that responds to +call+ for custom typecasting behavior.
+
 Now, we can create some animals. Let's start with a crow.
 
   crow = Bird.create(
@@ -132,6 +136,8 @@ Let's make sure the attributes got cast to the proper type:
   => 6
   lolrus.in_possession_of_bucket
   => true
+  lolrus.also_known_as
+  => "aka The Holder of the Bucket"
 
 That lolrus looks to be in fine shape, indeed.
 
@@ -143,10 +149,10 @@ 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
+* 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!

data/lib/attr_bucket/version.rb

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

data/lib/attr_bucket.rb

@@ -1,10 +1,12 @@
 module AttrBucket
-  def self.included(base)
+  def self.included(base) #:nodoc:
     base.extend ClassMethods
   end
 
   private
 
+  # Retrieve the attribute bucket, or if it's not yet a Hash,
+  # initialize it as one.
   def get_attr_bucket(name)
     unless read_attribute(name).is_a?(Hash)
       write_attribute(name, {})
@@ -12,8 +14,17 @@ module AttrBucket
     read_attribute(name)
   end
 
+  # Swipe the nifty column typecasting from the column class
+  # underlying the bucket column, or use the call method of
+  # the object supplied for +type+ if it responds to call.
+  #
+  # This allows custom typecasting by supplying a proc, etc
+  # as the value side of the hash in an attr_bucket definition.
   def explicitly_type_cast(value, type, column_class)
     return nil if value.nil?
+
+    return type.call(value) if type.respond_to?(:call)
+
     case type
       when :string    then value.to_s
       when :text      then value.to_s
@@ -33,12 +44,40 @@ module AttrBucket
   module ClassMethods
     private
 
+    # Accepts an options hash of the format:
+    #
+    #   :<bucket-name> => <bucket-attributes>,
+    #   [:<bucket-name> => <bucket-attributes>], [...]
+    #
+    # where <tt><bucket-name></tt> is the +text+ column being used for
+    # serializing the objects, and <tt><bucket-attributes></tt> is:
+    #
+    # * A single attribute name in symbol format (not much point...)
+    # * An array of attribute names
+    # * A hash, in which the keys are the attribute names in Symbol format,
+    #   and the values describe what they should be typecast as. The valid
+    #   choices are +string+, +text+, +integer+, +float+, +decimal+, +datetime+,
+    #   +timestamp+, +time+, +date+, +binary+, or +boolean+. This will invoke
+    #   the same typecasting behavior as is normally used by the underlying
+    #   ActiveRecord column (specific to your database).
+    #
+    # Alternately, you may specify a Proc or another object that responds to
+    # +call+, and it will be invoked with the value being assigned to the
+    # attribute as its only parameter, for custom typecasting behavior.
+    #
+    # Example:
+    #
+    #   attr_bucket :bucket => {
+    #     :is_awesome       => :boolean
+    #     :circumference    => :integer,
+    #     :flanderized_name => proc {|val| "#{val}-diddly"}
+    #   }
     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"
+                "#{bucket_name} is of type #{bucket_column.type}, not text"
         end
         serialize bucket_name, Hash
 
@@ -58,13 +97,13 @@ module AttrBucket
 
     alias :i_has_a_bucket :attr_bucket
 
-    def define_bucket_reader(bucket_name, attr_name)
+    def define_bucket_reader(bucket_name, attr_name) #:nodoc:
       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, column_class)
+    def define_bucket_writer(bucket_name, attr_name, attr_type, column_class) #:nodoc:
       define_method "#{attr_name}=" do |val|
         # TODO: Make this more resilient/granular for multiple bucketed changes
         send("#{bucket_name}_will_change!")

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Ernie Miller
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-27 00:00:00 -05:00
+date: 2011-01-28 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency