piggyback 0.2.2 → 0.2.3

data/CHANGELOG

@@ -1,3 +1,7 @@
+= 0.2.3 / 2011-03-21
+
+  * Updated documentation.
+
 = 0.2.2 / 2011-03-21
 
   * Removed `piggyback_sql` method in favor of `piggyback_attributes`.

data/README.markdown

@@ -9,7 +9,7 @@ Piggybacking refers to the technique of dynamically including attributes from an
 This is best illustrated in an example. Consider these models:
 
     class Author < ActiveRecord::Base
-      has_many :articles
+      has_many :posts
     end
     
     class Post < ActiveRecord::Base
@@ -18,43 +18,43 @@ This is best illustrated in an example. Consider these models:
     
 ActiveRecord supports piggybacking simply by joining the associated table and selecting columns from it:
 
-    >> post = Post.joins(:author).select('posts.*, author.name AS author_name').first
+    post = Post.joins(:author).select('posts.*, author.name AS author_name').first
 
-    >> post.title
-    => "Why piggybacking in ActiveRecord is flawed"
+    post.title
+    # => "Why piggybacking in ActiveRecord is flawed"
     
-    >> post.author_name
-    => "Alec Smart"
+    post.author_name
+    # => "Alec Smart"
     
-As you can see, the `name` attribute from `Author` is treated as if it were an attribute of `User`. ActiveRecord dynamically determines a model's attributes from the result set returned by the database. Every column in the result set becomes an attribute of the instantiated ActiveRecord objects. Whether the columns originate from the model's own or from a foreign table doesn't make a difference.
+As you can see, the `name` attribute from `Author` is treated as if it were an attribute of `Post`. ActiveRecord dynamically determines a model's attributes from the result set returned by the database. Every column in the result set becomes an attribute of the instantiated ActiveRecord objects. Whether the columns originate from the model's own or from a foreign table doesn't make a difference.
 
 Or so it seems. Actually there is a drawback which becomes obvious when we select non-string columns:
 
-    >> post = Post.joins(:author).select('posts.*, author.birthday AS author_birthday, author.rating AS author_rating').first
+    post = Post.joins(:author).select('posts.*, author.birthday AS author_birthday, author.rating AS author_rating').first
 
-    >> post.author_birthday
-    => "2011-03-01"
+    post.author_birthday
+    # => "2011-03-01"
 
-    >> post.author_rating
-    => "4.5"
+    post.author_rating
+    # => "4.5"
     
-Any attributes originating from foreign tables are not automatically type-casted as we would expect. This is because the database always returns results in text format. The model only knows about the data types of the columns in its own table. Since this information is used when ActiveRecord does its type-casting magic, it doesn't work with foreign columns.
+Any attributes originating from the `authors` table are treated as strings instead of being automatically type-casted as we would expect. The database returns result sets as plain text and ActiveRecord needs to obtain type information separately from the table schema in order to do its type-casting magic. Unfortunately, a model only knows about the columns types in its own table, so type-casting doesn't work with columns selected from foreign tables.
 
-We could work around this by defining attribute reader methods in the `Post` model that implicitly converts the values:
+We could work around this by defining attribute reader methods in the `Post` model that implicitly convert the values:
 
     class Post < ActiveRecord::Base
-      ...
+      belongs_to :author
       
       def author_birthday
-        Date.parse(read_attribute('author_birthday'))
+        Date.parse(read_attribute(:author_birthday))
       end
       
       def author_rating
-        read_attribute('author_rating').to_f
+        read_attribute(:author_rating).to_f
       end
     end
     
-However this is tedious, error-prone and repetitive if you do it in many models. The type-casting code shown above isn't solid and would be more complex in a real-life situation in order to deal with `nil` values, for example.
+However this is tedious, error-prone and repetitive if you do it in many models. The type-casting code shown above isn't solid and would quickly become more complex in a real-life application. In its current state it won't handle `nil` values properly, for example.
 
     
 ### Piggyback to the rescue!
@@ -71,13 +71,13 @@ You simply declare which association you want to piggyback and how the attribute
 
 Now you can do the following:
 
-    >> post = Post.piggyback(:author).first
+    post = Post.piggyback(:author).first
 
-    >> post.author_birthday
-    => Tue, 01 Mar 2011
+    post.author_birthday
+    # => Tue, 01 Mar 2011
 
-    >> post.author_rating
-    => 4.5
+    post.author_rating
+    # => 4.5
 
 The type-casting works with any type of attribute, even with serialized ones.
 
@@ -104,7 +104,7 @@ If you want to use an SQL-expression for selecting an attribute, Piggyback can a
       piggybacks :author, :author_name => "authors.first_name || ' ' || authors.last_name" 
     end
 
-    >> post.author_name
-    => "Donald Duck"
+    post.author_name
+    # => "Donald Duck"
     
 In fact, every value you pass in as a string will be treated as raw SQL in the SELECT clause.

data/Rakefile

@@ -1,7 +1,7 @@
 require 'rake'  
 require 'echoe'  
   
-Echoe.new('piggyback', '0.2.2') do |p|  
+Echoe.new('piggyback', '0.2.3') do |p|  
   p.description     = "Piggyback attributes from associated models with ActiveRecord"  
   p.url             = "http://github.com/juni0r/piggyback"  
   p.author          = "Andreas Korth"  

data/piggyback.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{piggyback}
-  s.version = "0.2.2"
+  s.version = "0.2.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andreas Korth"]

metadata

@@ -2,7 +2,7 @@
 name: piggyback
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors: 
 - Andreas Korth