piggyback 0.1.0 → 0.2.0

data/CHANGELOG

@@ -0,0 +1,3 @@
+v0.2 Leaner codebase by taking better advantage of AR-ecosystem. Improved specs. 
+
+v0.1 Initial version

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+
+Copyright (c) 2011 Andreas Korth
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -1,6 +1,10 @@
-README.rdoc
+CHANGELOG
+MIT-LICENSE
+README.markdown
 Rakefile
 lib/piggyback.rb
+piggyback.gemspec
+spec/models.rb
 spec/piggyback_spec.rb
 spec/spec_helper.rb
 Manifest

data/README.markdown

@@ -0,0 +1,110 @@
+# Piggyback
+
+An extension for piggybacking of ActiveRecord™ models.
+
+### What is Piggybacking?
+
+Piggybacking refers to the technique of dynamically including attributes from an associated object into the master object. This is achieved by joining the associated object's table in a database query and selecting the attributes that should be included with the parent object.
+
+This is best illustrated in an example. Consider these models:
+
+    class Author < ActiveRecord::Base
+      has_many :articles
+    end
+    
+    class Post < ActiveRecord::Base
+      belongs_to :author
+    end
+    
+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.title
+    => "Why piggybacking in ActiveRecord is flawed"
+    
+    >> 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.
+
+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.author_birthday
+    => "2011-03-01"
+
+    >> 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.
+
+We could work around this by defining attribute reader methods in the `Post` model that implicitly converts the values:
+
+    class Post < ActiveRecord::Base
+      ...
+      
+      def author_birthday
+        Date.parse(read_attribute('author_birthday'))
+      end
+      
+      def author_rating
+        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.
+
+    
+### Piggyback to the rescue!
+
+Piggyback introduces the `piggybacks` directive which allows us to easily define which attributes we want to piggyback from associated models. Not only does it take care of the type-casting but also provides us with some additional benefits.
+
+You simply declare which association you want to piggyback and how the attribute names should be mapped:
+
+    class Post < ActiveRecord::Base
+      belongs_to :author
+      
+      piggybacks :author, :birthday => :author_birthday, :rating => :author_rating 
+    end
+
+Now you can do the following:
+
+    >> post = Post.piggyback(:author).first
+
+    >> post.author_birthday
+    => Tue, 01 Mar 2011
+
+    >> post.author_rating
+    => 4.5
+
+The type-casting works with any type of attribute, even with serialized ones.
+
+As you can see, the `piggibacks` statement replaces the `joins` and `select` parts of the query. Using it is optional but makes life easier since you don't have to write the SQL for `select` by hand.
+
+Of course, `piggibacks` plays nice with Arel and you can add additional `joins`, `select` and other statements as you like, for example:
+
+    Post.select('posts.title, posts.body').piggibacks(:author).joins(:comments).where(:published => true)
+
+__Please note:__ If you want to restrict the columns selected from the master table as in the example above, you have to do so _before_ the `piggibacks` statement. Otherwise it will insert the select-all wildcard `SELECT posts.*` rendering your column selection useless.
+
+If you don't need to map the attribute names of the piggybacked model, you can simply do:
+
+    piggyback :author, [:name, :birthday, :rating]
+
+
+### Computed values
+
+If you want to use an SQL-expression for selecting an attribute, Piggyback can also help you with that. If `Author` didn't have a single `name` attribute, but `first_name` and `last_name`, you could concatenate them into a single attribute:
+
+    class Post < ActiveRecord::Base
+      belongs_to :author
+  
+      piggybacks :author, :author_name => "authors.first_name || ' ' || authors.last_name" 
+    end
+
+    >> 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,14 +1,15 @@
-require 'rubygems'  
 require 'rake'  
 require 'echoe'  
   
-Echoe.new('piggyback', '0.1.0') do |p|  
-  p.description     = "Piggyback associated models with ActiveRecord"  
+Echoe.new('piggyback', '0.2.0') do |p|  
+  p.description     = "Piggyback attributes from associated models with ActiveRecord"  
   p.url             = "http://github.com/juni0r/piggyback"  
   p.author          = "Andreas Korth"  
   p.email           = "andreas.korth@gmail.com"  
   p.ignore_pattern  = ["tmp/*", "log/*", "Gemfile", "Gemfile.lock"]
-  p.development_dependencies = []  
+
+  p.runtime_dependencies     = ["activerecord >=3.0.0"] 
+  p.development_dependencies = ["rspec", "sqlite3"]
 end  
   
 Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/lib/piggyback.rb

@@ -1,95 +1,109 @@
 module Piggyback
   extend ActiveSupport::Concern
   
-  included do |model|
-    model.class_inheritable_hash :piggyback_associations
-    model.piggyback_associations = {}
-
-    model.class_inheritable_hash :piggyback_attributes        
-    model.piggyback_attributes = {}
-  end
-  
-  class Association
+  class Association #:nodoc:
+    
+    def initialize(reflection, mappings = {})
+      @reflection = reflection
+      @mappings   = mappings
+    end
+    
+    def add_mappings(mappings)
+      @mappings.merge!(mappings)
+    end
+    
+    def map(&block)
+      @mappings.map(&block)
+    end
+    
+    def has_attribute?(attr_name)
+      @mappings.has_key? attr_name
+    end
     
-    attr_reader :reflection, :attributes
+    def column(attr_name)
+      @reflection.klass.columns_hash[@mappings[attr_name]]
+    end
+
+    def serialized_attribute(attr_name)
+      @reflection.klass.serialized_attributes[@mappings[attr_name]]
+    end
     
-    def initialize(*args)
-      @reflection, @attributes = *args
+    def quoted_table_name
+      @reflection.klass.quoted_table_name
     end
   end
 
   module ClassMethods
-
-    def piggy(*associations)
-      columns = piggyback_attributes.values_at(*associations).map do |association|
-        table_name = association.reflection.klass.quoted_table_name
-        association.attributes.map do |attribute, mapping|
-          if attribute != mapping
-            "#{table_name}.#{connection.quote_column_name(mapping)} AS #{attribute}"
-          else
-            "#{table_name}.#{connection.quote_column_name(attribute)}"
-          end
-        end
-      end
-      columns.flatten!
-      columns.unshift("#{quoted_table_name}.*") unless scoped.select_values.any?
-      select(columns.join(', ')).joins(*associations)
+    
+    def piggyback_associations
+      read_inheritable_attribute(:piggyback_associations) || write_inheritable_attribute(:piggyback_associations, {})
     end
     
+    def piggyback_association_for_attribute(attr_name)
+      piggyback_associations.each_value.detect{ |association| association.has_attribute? attr_name }
+    end
     
-    def piggyback(association, *unmapped_attributes)
+    def piggybacks(association, *attributes)
       
+      attributes.flatten!
+      mapped_attributes = attributes.extract_options!
       reflection = reflect_on_association(association.to_sym)
-
-      unless reflection
-        raise ArgumentError.new("#{self.class.name} has no association named '#{association}'.") 
-      end
-
-      unless [:belongs_to, :has_one].include?(reflection.macro)
-        raise ArgumentError.new("Only belongs_to and has_many associations can be used for piggybacking.")
-      end
-      
-      mapped_attributes = unmapped_attributes.extract_options!
-      unmapped_attributes.concat(Array(mapped_attributes.delete(:attributes)))
       
-      attributes = {}
+      raise ArgumentError, "#{name} has no association named '#{association}'"           if reflection.nil?
+      raise ArgumentError, "Piggyback only supports belongs_to and has_one associations" if reflection.collection?
+      raise ArgumentError, "No attributes specified for piggybacking"                    if attributes.empty?
+            
+      mappings = {}
       
-      unmapped_attributes.flatten.each do |attr_name|
-        attr_name = attr_name.to_s
-        attributes[attr_name] = attr_name
+      attributes.each do |attr_name|
+        mappings[attr_name.to_s] = attr_name.to_s
       end
       
-      mapped_attributes.each do |attr_name, mapping|
-        attributes[attr_name.to_s] = mapping.to_s
+      mapped_attributes.each do |attr_name, mapped_name|
+        mappings[attr_name.to_s] = mapped_name.is_a?(String) ? Arel.sql(mapped_name) : mapped_name.to_s
       end
 
-      association = Association.new(reflection, attributes)
+      association = (piggyback_associations[reflection.name] ||= Association.new(reflection))
+      association.add_mappings(mappings)
 
-      piggyback_attributes[reflection.name] = association      
-      
-      attributes.each do |attr_name, mapping|
-        piggyback_associations[attr_name] = association
-        define_method attr_name do
-          if @attributes.has_key?(attr_name) 
-            read_attribute(attr_name)
-          else
-            send(reflection.name).send(mapping)
-          end
-        end
-      end
+      # These default procs for +columns_hash+ and +serialized_attributes+
+      # allow +read_attribute+ to work transparently and consistently with 
+      # attributes from joined models. They rely heavily on the implementation
+      # of +read_attribute+ and related methods. Since ActiveRecord doesn't
+      # provide hooks for overriding this behavior, it is the simplest and
+      # least intrusive way to implement proper type casting for attributes
+      # while avoiding code duplication.
       
       columns_hash.default_proc = lambda do |hash, attr_name|
-        if association = piggyback_associations[attr_name]
-          association.reflection.klass.columns_hash[attr_name]
+        if association = piggyback_association_for_attribute(attr_name)
+          association.column(attr_name)
         end
       end
 
       serialized_attributes.default_proc = lambda do |hash, attr_name|
-        if association = piggyback_associations[attr_name]
-          association.reflection.klass.serialized_attributes[attr_name]
+        if association = piggyback_association_for_attribute(attr_name)
+          association.serialized_attribute(attr_name)
         end
       end
     end
+
+    def piggyback(*associations)
+      columns = piggyback_associations.values_at(*associations).map do |association|
+        association.map do |attr_name, mapped_name|
+          if attr_name != mapped_name
+            if mapped_name.is_a? Arel::Nodes::SqlLiteral
+              "#{mapped_name} AS #{attr_name}"
+            else
+              "#{association.quoted_table_name}.#{connection.quote_column_name(mapped_name)} AS #{attr_name}"
+            end
+          else
+            "#{association.quoted_table_name}.#{connection.quote_column_name(attr_name)}"
+          end
+        end
+      end
+      columns.unshift("#{quoted_table_name}.*") unless scoped.select_values.any?
+      select(columns.flatten.join(', ')).joins(*associations)
+    end
   end
 end
 

data/piggyback.gemspec

@@ -2,28 +2,37 @@
 
 Gem::Specification.new do |s|
   s.name = %q{piggyback}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andreas Korth"]
-  s.date = %q{2011-03-20}
-  s.description = %q{Piggyback associated models with ActiveRecord}
+  s.date = %q{2011-03-21}
+  s.description = %q{Piggyback attributes from associated models with ActiveRecord}
   s.email = %q{andreas.korth@gmail.com}
-  s.extra_rdoc_files = ["README.rdoc", "lib/piggyback.rb"]
-  s.files = ["README.rdoc", "Rakefile", "lib/piggyback.rb", "spec/piggyback_spec.rb", "spec/spec_helper.rb", "Manifest", "piggyback.gemspec"]
+  s.extra_rdoc_files = ["CHANGELOG", "README.markdown", "lib/piggyback.rb"]
+  s.files = ["CHANGELOG", "MIT-LICENSE", "README.markdown", "Rakefile", "lib/piggyback.rb", "piggyback.gemspec", "spec/models.rb", "spec/piggyback_spec.rb", "spec/spec_helper.rb", "Manifest"]
   s.homepage = %q{http://github.com/juni0r/piggyback}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Piggyback", "--main", "README.rdoc"]
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Piggyback", "--main", "README.markdown"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{piggyback}
   s.rubygems_version = %q{1.5.2}
-  s.summary = %q{Piggyback associated models with ActiveRecord}
+  s.summary = %q{Piggyback attributes from associated models with ActiveRecord}
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activerecord>, [">= 3.0.0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 0"])
     else
+      s.add_dependency(%q<activerecord>, [">= 3.0.0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<sqlite3>, [">= 0"])
     end
   else
+    s.add_dependency(%q<activerecord>, [">= 3.0.0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<sqlite3>, [">= 0"])
   end
 end

data/spec/models.rb

@@ -0,0 +1,44 @@
+silence_stream(STDOUT) do
+  ActiveRecord::Schema.define(:version => 1) do
+
+    create_table :essentials do |t|
+      t.string :token
+      t.timestamps
+    end
+
+    create_table :details do |t|
+      t.belongs_to :essential
+
+      t.string  :first_name
+      t.string  :last_name
+      t.string  :words
+      t.integer :count
+      t.boolean :checked
+      t.date    :birthday
+      t.text    :baggage
+
+      t.timestamps
+    end
+  end
+end
+
+class Essential < ActiveRecord::Base
+  has_one :detail, :inverse_of => :essential
+  has_many :details
+  
+  piggybacks :detail, [:first_name, :last_name, :count, :checked, :birthday, :baggage], 
+    :name => "details.first_name || ' ' || details.last_name",
+    :detail_updated_at => :updated_at
+end
+
+class Detail < ActiveRecord::Base
+  belongs_to :essential, :inverse_of => :detail
+
+  serialize :baggage
+
+  piggybacks :essential, :token
+
+  def name
+    "#{first_name} #{last_name}"
+  end
+end

data/spec/piggyback_spec.rb

@@ -2,33 +2,76 @@ require 'spec_helper'
 
 describe Piggyback do
   
-  before do
-    Essential.create(:position => 1).create_detail(
-      :name     => "nice",
-      :awesome  => true,
-      :position => 23,
-      :birthday => "18.12.1974",
-      :baggage  => {:key => "value"})
+  context "directive" do
+    
+    def definition_should_raise(message, &block)
+      lambda{ Essential.class_eval(&block) }.should raise_error(ArgumentError, message)
+    end
+    
+    it "should require the association to be defined" do
+      definition_should_raise "Essential has no association named 'bogus'" do
+        piggybacks :bogus, [:attribute]
+      end
+    end
+    
+    it "should not work with has_many associations" do
+      definition_should_raise "Piggyback only supports belongs_to and has_one associations" do
+        piggybacks :details, [:attribute]
+      end
+    end
+    
+    it "should require attributes" do
+      definition_should_raise "No attributes specified for piggybacking" do
+        piggybacks :detail
+      end
+    end
   end
   
-  it "should read attributes" do
-    e = Essential.piggy(:detail).first
-    e.should_not_receive(:detail)
-    e.name.should eql("nice")
-    e.awesome.should be_true
-    e.position.should eql(1)
-    e.rank.should eql(23)
-    e.birthday.should eql(Date.new(1974,12,18))
-    e.baggage.should eql({:key => "value"})
-  end
+  context "relation" do
+
+    let :essential do 
+      Essential.create(:token => "TOKEN").create_detail(
+        :first_name => "John",
+        :last_name  => "Doe",
+        :count      => 23,
+        :checked    => false,
+        :birthday   => "18.12.1974",
+        :baggage    => {:key => "value"})
+      
+      Essential.piggyback(:detail).first
+    end
+
+    it "should not load the association" do
+      essential.should_not_receive(:detail)
+      essential.first_name.should be_present
+    end
+    
+    it "should read string attributes" do
+      essential.first_name.should eql("John")
+    end
+
+    it "should read integer attributes" do
+      essential.count.should eql(23)
+    end
+
+    it "should read boolean attributes" do
+      essential.checked.should eql(false)
+    end
+
+    it "should read date attributes" do
+      essential.birthday.should eql(Date.new(1974,12,18))
+    end
 
-  it "should read attributes from the association" do
-    e = Essential.first
-    e.name.should eql("nice")
-    e.awesome.should be_true
-    e.position.should eql(1)
-    e.rank.should eql(23)
-    e.birthday.should eql(Date.new(1974,12,18))
-    e.baggage.should eql({:key => "value"})
+    it "should read serialized attributes" do
+      essential.baggage.should eql({:key => "value"})
+    end
+    
+    it "should read a mapped attribute" do
+      essential.detail_updated_at.should be_instance_of(Time)
+    end
+    
+    it "should read computed attributes" do
+      essential.name.should eql("John Doe")
+    end
   end
 end

data/spec/spec_helper.rb

@@ -1,12 +1,8 @@
-Root = Pathname.new(File.expand_path(File.join(File.dirname(__FILE__), '..')))
+GEM_ROOT = File.expand_path('../..',__FILE__)
+$: << File.join(GEM_ROOT,'lib')
 
-$: << Root.join('lib')
-
-require 'fileutils'
 require 'active_record'
-# require 'active_support/buffered_logger'
 require 'piggyback'
-require 'rspec'
 
 RSpec.configure do |config|
   config.before do 
@@ -15,35 +11,6 @@ RSpec.configure do |config|
 end
 
 ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:", :verbosity => "silent")
-ActiveRecord::Base.logger = ActiveSupport::BufferedLogger.new(Root.join('log','test.log'))
-
-silence_stream(STDOUT) do
-  ActiveRecord::Schema.define(:version => 1) do
-    create_table :essentials do |t|
-      t.integer :position
-      t.timestamps
-    end
-
-    create_table :details do |t|
-      t.belongs_to :essential
-      t.string  :name
-      t.integer :position
-      t.boolean :awesome
-      t.date    :birthday
-      t.text    :baggage
-      t.timestamps
-    end
-  end
-end
-
-class Essential < ActiveRecord::Base
-  has_one :detail  
-  # piggyback :detail, :attributes => [:name, :awesome, :birthday, :baggage], :rank => :position
-  # piggyback :detail, :name, :awesome, :birthday, :baggage, :rank => :position
-  piggyback :detail, [:name, :awesome, :birthday, :baggage], :rank => :position
-end
+ActiveRecord::Base.logger = ActiveSupport::BufferedLogger.new(File.join(GEM_ROOT,'log','test.log'))
 
-class Detail < ActiveRecord::Base
-  belongs_to :essential
-  serialize :baggage
-end
+require 'models'

metadata

@@ -2,7 +2,7 @@
 name: piggyback
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Andreas Korth
@@ -10,27 +10,63 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-20 00:00:00 +01:00
+date: 2011-03-21 00:00:00 +01:00
 default_executable: 
-dependencies: []
-
-description: Piggyback associated models with ActiveRecord
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sqlite3
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Piggyback attributes from associated models with ActiveRecord
 email: andreas.korth@gmail.com
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- README.rdoc
+- CHANGELOG
+- README.markdown
 - lib/piggyback.rb
 files: 
-- README.rdoc
+- CHANGELOG
+- MIT-LICENSE
+- README.markdown
 - Rakefile
 - lib/piggyback.rb
+- piggyback.gemspec
+- spec/models.rb
 - spec/piggyback_spec.rb
 - spec/spec_helper.rb
 - Manifest
-- piggyback.gemspec
 has_rdoc: true
 homepage: http://github.com/juni0r/piggyback
 licenses: []
@@ -42,7 +78,7 @@ rdoc_options:
 - --title
 - Piggyback
 - --main
-- README.rdoc
+- README.markdown
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -63,6 +99,6 @@ rubyforge_project: piggyback
 rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
-summary: Piggyback associated models with ActiveRecord
+summary: Piggyback attributes from associated models with ActiveRecord
 test_files: []