attribute-views 0.1.0

data/LICENSE

@@ -0,0 +1,18 @@
+(c) 2009 Fingertips, Manfred Stienstra <m.stienstra@fngtps.com>
+
+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 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/README.rdoc

@@ -0,0 +1 @@
+= Attribute-Views

data/lib/active_record/attribute_views.rb

@@ -0,0 +1,110 @@
+module ActiveRecord
+  class AttributeView
+    attr_accessor :attributes
+    
+    def initialize(*attributes)
+      self.attributes = attributes
+    end
+    
+    def get(record)
+      load(*attributes.map { |attribute| record.send(attribute) })
+    end
+    
+    def load(*values)
+      raise NoMethodError, "Please implement the `load' method on your view class"
+    end
+    
+    def set(record, input)
+      parsed = Array(parse(input))
+      record.attributes = Hash[*attributes.zip(parsed).flatten]
+    end
+    
+    def parse(input)
+      raise NoMethodError, "Please implement the `parse' method on your view class"
+    end
+  end
+  
+  # Attribute views translate between value object in your application and columns in your database. A value object
+  # is basically any object that represents a value, for example an IP address or a rectangle. A database has a
+  # limited number of values it can represent internally. In order to store value object we need some sort of
+  # conversion from the value object to database columns. In order to read the value object we need a conversion
+  # from columns to a value object.
+  #
+  # Note that attribute views are a really flexible concept and in some cases it's perfectly fine to use a string
+  # as the value object. Later on we will look at an example of this.
+  #
+  # = Defining views
+  #
+  # In order to create an attribute view you need to create a class that takes care of the conversion between
+  # column values and your value object. The easiest way to create a view class is by subclassing from
+  # ActiveRecord::AttributeView and implementing two methods: <code>load</code> and <code>parse</code>.
+  #
+  # The <code>load</code> method receives the column values from the record and returns the value object. The
+  # <code>parse</code> method receives the value object and returns a list of column values.
+  #
+  # Let's assume we want to describe a plot in the lots table with the following schema:
+  #
+  #   ActiveRecord::Schema.define do
+  #     create_table :lots do |t|
+  #       t.integer :price_in_cents
+  #       t.integer :position_x
+  #       t.integer :position_y
+  #       t.integer :position_width
+  #       t.integer :position_height
+  #     end
+  #   end
+  #
+  # In our application we're going to handle the position of the Lot very often so we want to access it through
+  # a value object. We write the following value object to represent it as a rectangle:
+  #
+  #   class Rectangle
+  #     attr_accessor :x1, :y1, :x2, :y2
+  #
+  #     def initialize(x1, y1, x2, y2)
+  #       @x1, @y1, @x2, @y2 = x1, y1, x2, y2
+  #     end
+  #   end
+  #
+  #   class Lot < ActiveRecord::Base
+  #     views :position, :as => RectangleView.new(:position_x, :position_y, :position_width, :position_height)
+  #   end
+  #
+  #   class RectangleView < ActiveRecord::AttributeView
+  #     def load(x, y, width, height)
+  #       Rectangle.new(x, y, x + width, y + height)
+  #     end
+  #
+  #     def parse(rectangle)
+  #       [rectangle.x1, rectangle.y1, (rectangle.x2 - rectangle.x1), (rectangle.y2 - rectangle.y1)]
+  #     end
+  #   end
+  module AttributeViews
+    def views(name, options={})
+      options.assert_valid_keys(:as)
+      raise ArgumentError, "Please specify a view object with the :as option" unless options.has_key?(:as)
+      
+      view_name = "#{name}_view"
+      
+      define_method(view_name) do
+        options[:as]
+      end
+      
+      class_eval <<-READER_METHODS, __FILE__, __LINE__
+        def #{name}                                       # def starts_at
+          #{view_name}.get(self)                          #   starts_at_view.get(self)
+        end                                               # end
+      READER_METHODS
+      
+      class_eval <<-WRITER_METHODS, __FILE__, __LINE__
+        def #{name}_before_type_cast                      # def starts_at_before_type_cast
+          @#{name}_before_type_cast || #{name}            #   @starts_at_before_type_cast || starts_at
+        end                                               # end
+        
+        def #{name}=(value)                               # def starts_at=(value)
+          @#{name}_before_type_cast = value               #   @starts_at_before_type_cast = value
+          #{view_name}.set(self, value)                   #   starts_at_view.set(self, value)
+        end                                               # end
+      WRITER_METHODS
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1,2 @@
+require 'active_record/attribute_views'
+ActiveRecord::Base.send(:extend, ActiveRecord::AttributeViews)

data/test/cases/attribute_view_test.rb

@@ -0,0 +1,54 @@
+require File.expand_path('../../test_helper.rb', __FILE__)
+
+class AttributeViewTest < ActiveSupport::TestCase
+  def setup
+    @view = ActiveRecord::AttributeView.new(:start_date, :start_time)
+  end
+  
+  test "view stores the attributes it composes" do
+    assert_equal [:start_date, :start_time], @view.attributes
+  end
+  
+  test "view gets a value object using a record" do
+    date = Date.new(2009, 5, 24)
+    time = Time.parse('23:00')
+    event = Event.new(:start_date => date, :start_time => time)
+    value = mock('Value')
+    
+    @view.expects(:load).with(date, time).returns(value)
+    assert_equal value, @view.get(event)
+  end
+  
+  test "view warns the programmer to inplement the load method" do
+    begin
+      @view.load
+    rescue NoMethodError => e
+      assert_equal "Please implement the `load' method on your view class", e.message
+    else
+      fail 'Should raise a NoMethodError'
+    end
+  end
+  
+  test "view sets a value object on a record" do
+    date = Date.new(2009, 5, 24)
+    time = Time.parse('23:00')
+    event = Event.new
+    input = '24 5 23:00'
+    
+    @view.stubs(:parse).returns([date, time])
+    @view.set(event, input)
+    
+    assert_equal date, event.start_date
+    assert_equal time, event.start_time
+  end
+  
+  test "view warns the programmer to inplement the parse method" do
+    begin
+      @view.parse('24 5 23:00')
+    rescue NoMethodError => e
+      assert_equal "Please implement the `parse' method on your view class", e.message
+    else
+      fail 'Should raise a NoMethodError'
+    end
+  end
+end

data/test/cases/attribute_views_test.rb

@@ -0,0 +1,93 @@
+require File.expand_path('../../test_helper.rb', __FILE__)
+
+class AttributeViewsClassmethodsTest < ActiveSupport::TestCase
+  test "views should raise argument error about invalid option keys" do
+    begin
+      Event.send(:views, :formatted_fee, :as => FeeFormatter.new(:fee_in_cents), :invalid => :should_raise)
+    rescue ArgumentError => e
+      assert_match /invalid/, e.message
+    else
+      fail 'Should raise an ArgumentError'
+    end
+  end
+  
+  test "views should raise argument error about missing :as option" do
+    begin
+      Event.send(:views, :formatted_fee)
+    rescue ArgumentError => e
+      assert_equal "Please specify a view object with the :as option", e.message
+    else
+      fail 'Should raise an ArgumentError'
+    end
+  end
+  
+  test "views should define a reader method for the view object" do
+    assert_respond_to Event.new, :starts_at_view
+  end
+  
+  test "views should define a reader method for the value object" do
+    assert_respond_to Event.new, :starts_at
+  end
+  
+  test "views should define a reader method for the value object before type cast" do
+    assert_respond_to Event.new, :starts_at_before_type_cast
+  end
+  
+  test "views should define a writer method for the value object" do
+    assert_respond_to Event.new, :starts_at=
+  end
+end
+
+class AttributeViewsFunctionTest < ActiveSupport::TestCase
+  def setup
+    @input = '24 May 23:00'
+    @value = "24 May 2009 23:00"
+    
+    @date = Date.new(2009, 5, 24)
+    @time = Time.parse('23:00')
+    @event = Event.new(:start_date => @date, :start_time => @time)
+  end
+  
+  test "view object reader should return the view object" do
+    assert_kind_of CompositeDatetime, @event.starts_at_view
+  end
+  
+  test "view object reader should always return the same view object" do
+    assert_equal Event.new.starts_at_view, Event.new.starts_at_view
+  end
+  
+  test "value object reader method should return the value object" do
+    @event.starts_at_view.expects(:load).with(@date, @time).returns(@value)
+    assert_equal @value, @event.starts_at
+  end
+  
+  test "value object before type cast should be the value object when nothing was set" do
+    @event.starts_at_view.stubs(:load).with(@date, @time).returns(@value)
+    assert_equal @value, @event.starts_at_before_type_cast
+  end
+  
+  test "value object before type cast should be the input when it was just set" do
+    @event.starts_at = @input
+    assert_equal @input, @event.starts_at_before_type_cast
+  end
+  
+  test "value object writer should set attributes on the record" do
+    event = Event.new
+    event.starts_at_view.stubs(:parse).with(@input).returns([@date, @time])
+    
+    event.starts_at = @input
+    assert_equal @date, event.start_date
+    assert_equal @time, event.start_time
+  end
+  
+  test "value object writer should update attributes on the record" do
+    date = Date.new(2009, 12, 31)
+    time = Time.parse('01:00')
+    input = '31 12 01:00'
+    @event.starts_at_view.stubs(:parse).with(input).returns([date, time])
+    
+    @event.starts_at = input
+    assert_equal date, @event.start_date
+    assert_equal time, @event.start_time
+  end
+end

data/test/models/composite_datetime.rb

@@ -0,0 +1,7 @@
+class CompositeDatetime < ActiveRecord::AttributeView
+  def load(date, time)
+  end
+  
+  def parse(input)
+  end
+end

data/test/models/event.rb

@@ -0,0 +1,3 @@
+class Event < ActiveRecord::Base
+  views :starts_at, :as => CompositeDatetime.new(:start_date, :start_time)
+end

data/test/models/fee_formatter.rb

@@ -0,0 +1,4 @@
+class FeeFormatter < ActiveRecord::AttributeView
+  def load(fee_in_cents)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+require 'rubygems' rescue nil
+
+require 'active_support'
+require 'active_record'
+
+require 'test/unit'
+require 'active_support/test_case'
+
+require 'mocha'
+
+plugin_dir = File.expand_path('../../', __FILE__)
+$:.unshift(File.join(plugin_dir, 'lib'), File.join(plugin_dir, 'rails'))
+require 'init'
+
+test_dir = File.expand_path('../', __FILE__)
+$:.unshift(File.join(test_dir, 'cases'), File.join(test_dir, 'models'))
+require 'fee_formatter'
+require 'composite_datetime'
+require 'event'
+
+ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => ':memory:')
+
+ActiveRecord::Migration.verbose = false
+ActiveRecord::Schema.define(:version => 1) do
+  create_table :events, :force => true do |t|
+    t.integer :fee_in_cents
+    t.date :start_date
+    t.time :start_time
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: attribute-views
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Manfred Stienstra
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-26 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: A plugin converting between value objects and record columns.
+email: manfred@fngtps.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- lib/active_record/attribute_views.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://fingertips.github.com
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A plugin converting between value objects and record columns.
+test_files: 
+- test/cases/attribute_view_test.rb
+- test/cases/attribute_views_test.rb
+- test/models/composite_datetime.rb
+- test/models/event.rb
+- test/models/fee_formatter.rb
+- test/test_helper.rb