named_scope_for_time_attr 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 2009-03-02
+
+* Initial release
+

data/Manifest.txt

@@ -0,0 +1,12 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+init.rb
+lib/named_scope_for_time_attr.rb
+lib/named_scope_for_time_attr/named_scope_for_time_attr.rb
+script/destroy
+script/generate
+test/test_helper.rb
+test/test_named_scope_for_time_attr.rb

data/PostInstall.txt

@@ -0,0 +1,4 @@
+
+For more information on named_scope_for_time_attr, 
+see http://nsfta.rubyforge.org/
+

data/README.rdoc

@@ -0,0 +1,73 @@
+= named_scope_for_time_attr
+
+All information can be found here: http://nsfta.rubyforge.org/
+
+== DESCRIPTION:
+
+Provides the ActiveRecord helper method <tt>named_scope_for_time_attr</tt>.  
+Given the name of a time attribute of an ActiveRecord model 
+(e.g. <tt>created_at</tt> of <tt>Claim</tt>) it defines a correspondent
+named scope for easy access to an arbitrarily time range (scope).
+
+== FEATURES/PROBLEMS:
+
+* Defines a named scope for the given time attribute
+* Allows easy access to an arbitrarily time range
+* Defines a named scope <tt>order</tt> for easy ordering of the result
+
+== SYNOPSIS:
+	
+Define the named scope <tt>created_at</tt> and <tt>last_modified_on</tt>
+via <tt>named_scope_for_time_attr</tt>:
+	  
+  class Claim < ActiveRecord::Base
+    named_scope_for_time_attr :created_at, :order => 'created_at DESC'
+    named_scope_for_time_attr :last_modified_on, :limit => 10
+    ...
+  end
+  
+It is then possible to use the scope method <tt>created_at</tt> and <tt>updated_at</tt>
+as follows:
+  
+    Claim.created_at(2.days.ago)
+    Claim.created_at(2.days.ago, 1.days.ago)
+    Claim.created_at(:today)
+    Claim.created_at(:this_month).order('created_at DESC')
+    Claim.created_at(:q1) # quarter one
+    Claim.last_modified_on(3.weeks.ago, :limit => 20)
+    ...
+
+See API doc for class <tt>named_scope_for_time_attr</tt> for examples:
+
+== REQUIREMENTS:
+
+* ActiveRecord
+
+== INSTALL:
+
+* sudo gem install named_scope_for_time_attr
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009-* Thomas Baustert
+
+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/Rakefile

@@ -0,0 +1,28 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/named_scope_for_time_attr'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('named_scope_for_time_attr', NamedScopeForTimeAttr::VERSION) do |p|
+  p.developer('Thomas Baustert', 'business@thomasbaustert.de')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = "nsfta"
+  # p.extra_deps         = [
+  #   ['activesupport','>= 2.0.2'],
+  # ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/init.rb

@@ -0,0 +1,2 @@
+# Diese Datei macht aus dem Gem ein Rails Plugin
+require 'named_scope_for_time_attr'

data/lib/named_scope_for_time_attr.rb

@@ -0,0 +1,15 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'active_record'
+
+module NamedScopeForTimeAttr
+  VERSION = '1.0.0'
+end
+
+require File.expand_path(File.dirname(__FILE__) + '/named_scope_for_time_attr/named_scope_for_time_attr')
+
+# include the method in ActiveRecord::Base so it is available in all models by default
+ActiveRecord::Base.class_eval do
+  include NamedScopeForTimeAttr
+end

data/lib/named_scope_for_time_attr/named_scope_for_time_attr.rb

@@ -0,0 +1,162 @@
+module NamedScopeForTimeAttr #:nodoc:
+
+  def self.included(base)
+    base.extend ClassMethods 
+  end
+
+  module ClassMethods
+
+    ##
+    # Provides the <tt>ActiveRecord</tt> helper method <tt>named_scope_for_time_attr</tt>.  
+    # Given the name of a time attribute of an ActiveRecord model 
+    # (e.g. <tt>created_at</tt> of <tt>Claim</tt>) it defines a correspondent
+    # named scope for easy access to an arbitrarily time range (scope).
+    #
+    # ==== Examples
+    #
+    #   class Claim < ActiveRecord::Base
+    #     named_scope_for_time_attr :created_at, :order => 'created_at DESC'
+    #     named_scope_for_time_attr :updated_at
+    #     named_scope_for_time_attr :last_modified_on, :limit => 10
+    #     ...
+    #   end
+    #
+    # It is then possible to use the scope method <tt>created_at</tt> and <tt>updated_at</tt>
+    # as follows:
+    #
+    #   Claim.created_at(2.days.ago)
+    #   Claim.updated_at(2.days.ago, 1.days.ago)
+    #   Claim.last_modified_on(3.weeks.ago)
+    #
+    # Is is even possible to use one of the following predefined keys to specify a time range:
+    #
+    # * <tt>:today</tt>
+    # * <tt>:yesterday</tt>
+    # * <tt>:tomorrow</tt>
+    # * <tt>:this_week</tt>
+    # * <tt>:last_week</tt>
+    # * <tt>:next_week</tt>
+    # * <tt>:this_month</tt>
+    # * <tt>:last_month</tt>
+    # * <tt>:next_month</tt>
+    # * <tt>:this_quarter</tt>
+    # * <tt>:last_quarter</tt>
+    # * <tt>:next_quarter</tt>
+    # * <tt>:q1</tt>
+    # * <tt>:q2</tt>
+    # * <tt>:q3</tt>
+    # * <tt>:q4</tt>
+    # * <tt>:this_year</tt>
+    # * <tt>:last_year</tt>
+    # * <tt>:next_year</tt>
+    #
+    # And use them as follows:
+    # 
+    #   Claim.created_at(:today)
+    #   Claim.updated_at(:this_month)
+    #   Claim.last_modified_on(:last_year)
+    #   Claim.created_at(:q1) # quarter one
+    #   Claim.created_at(:this_quarter)
+    #
+    # One can specify additional conditional options to <tt>named_scope_for_time_attr</tt> 
+    # to sort or limit the list of object loaded:
+    #
+    #   class Claim < ActiveRecord::Base
+    #     named_scope_for_time_attr :created_at, :order => 'created_at DESC'
+    #     named_scope_for_time_attr :updated_at, :limit => 10
+    #     ...
+    #   end
+    #
+    # The definition also provide a scope <tt>order</tt> to ordered the list which is used
+    # as follows:
+    #
+    #   Claim.updated_at(:yesterday).order(:updated_at) # => ... ORDER BY created_at
+    #   Claim.updated_at(:last_week).order('updated_at DESC') # => ... ORDER BY updated_at DESC
+    #   Claim.updated_at(:yesterday).order('shortname') # => ... ORDER BY shortname
+    #
+    def named_scope_for_time_attr(attr_name, options = {})
+      named_scope attr_name, lambda { |*args| build_conditions("#{table_name}.#{attr_name}", *args).merge(options) }
+      named_scope :order, lambda { |*args| {:order => (args.first || "#{attr_name} DESC") } }
+    end
+  
+    private
+
+      QUARTER_KEYS = [:this_quarter, :last_quarter, :next_quarter, :q1, :q2, :q3, :q4].freeze
+      QUARTER_MONTHS = { 1 => [1,3], 2 => [4,6], 3 => [7,9], 4 => [10,12] }.freeze
+      MAP_TIME = {
+        :today        => [ 0, :day],
+        :yesterday    => [ 1, :day],
+        :tomorrow     => [-1, :day],
+        :this_week    => [ 0, :week],
+        :last_week    => [ 1, :week],
+        :next_week    => [-1, :week],
+        :this_month   => [ 0, :month],
+        :last_month   => [ 1, :month],
+        :next_month   => [-1, :month],
+        :this_year    => [ 0, :year],
+        :last_year    => [ 1, :year],
+        :next_year    => [-1, :year]
+      }
+
+      ##
+      # Examples:
+      #   build_conditions(:created_at, :last_week)
+      #   build_conditions(:created_at, 2.days.ago, 1.days.ago)
+      #   build_conditions(:created_at, 3.hours.ago)
+      #
+      def build_conditions(attr_name, *args)
+        if QUARTER_KEYS.include?(args.first)
+          quarter_range_conditions(attr_name, args.first)
+        elsif args.first.kind_of?(Symbol)
+          count, key = MAP_TIME[args.first]
+          time_range_conditions_ago(attr_name, count || 0, key || args.first)
+        elsif args.size == 2
+          time_range_conditions(attr_name, args.first, args.last)
+        else 
+          {:conditions => ["#{attr_name} >= ?", args.first]}
+        end
+      end
+
+      ##
+      # Examples:
+      #   time_range_conditions_ago(:created_at, 0, :day)
+      #   time_range_conditions_ago(:created_at, 1, :week)
+      #
+      def time_range_conditions_ago(attr_name, count, key)
+        eval("time_range_conditions(attr_name, #{count}.#{key}.ago.beginning_of_#{key}, #{count}.#{key}.ago.end_of_#{key})")
+      end
+
+      def time_range_conditions(attr_name, start_time, end_time)
+        {:conditions => ["#{attr_name} >= ? AND #{attr_name} <= ?", start_time, end_time]}
+      end
+
+      def quarter_range_conditions(attr_name, quarter)
+        year = Time.now.year
+        if quarter.to_s =~ /^q\d{1}/
+          quarter = quarter.to_s[1,1].to_i
+        else
+          month = Time.now.month
+          q = #TODO/2009-03-02/tb better code 
+            if month < 4
+              1
+            elsif month < 7
+              2
+            elsif month < 10
+              3
+            else
+              4
+            end
+          quarter = q   if quarter == :this_quarter  
+          quarter = q-1 if quarter == :last_quarter  
+          quarter = q+1 if quarter == :next_quarter  
+          quarter > 4 ? 1 : (quarter < 1 ? 4 : quarter)
+        end
+        start_month, end_month = QUARTER_MONTHS[quarter]
+        time_range_conditions(attr_name, 
+          Time.mktime(year, start_month).beginning_of_month, 
+          Time.mktime(year, end_month).end_of_month)
+      end
+
+  end
+end
+

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'test/unit'
+require 'rubygems' #needed for run tests in TextMate
+require File.expand_path(File.dirname(__FILE__) + '/../lib/named_scope_for_time_attr')
+

data/test/test_named_scope_for_time_attr.rb

@@ -0,0 +1,111 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+# The ActiveRecord test model. 
+# Note: we don't need a database as long as we only build named scopes.
+class Claim < ActiveRecord::Base
+  named_scope_for_time_attr :created_at
+  named_scope_for_time_attr :updated_at, :order => 'name DESC'
+end
+
+# Simulate a constant time. 
+# You can use mocha for this but than you have one dependency more.
+class Time
+  def self.now
+    Time.mktime(2009,3,1,12,0,0)
+  end
+end
+
+class TestNamedScopeForTimeAttr < Test::Unit::TestCase
+
+  # #TODO/2009-03-02/tb 
+  # tests gehen nicht auf die DB, d.h. das Statement wird nicht wirklich ausgeführt. ist das gut?
+
+  def test_scope_with_today
+    assert_conditions("2009-03-01  00:00:00", "2009-03-01 23:59:59", :today)
+  end
+
+  def test_scope_with_yesterday
+    assert_conditions("2009-02-28 00:00:00", "2009-02-28 23:59:59", :yesterday)
+  end
+
+  def test_scope_with_tomorrow
+    assert_conditions("2009-03-02 00:00:00", "2009-03-02 23:59:59", :tomorrow)
+  end
+
+  def test_scope_with_this_week           
+    assert_conditions("2009-02-23 00:00:00", "2009-03-01 23:59:59", :this_week)
+  end                                     
+                                          
+  def test_scope_with_last_week           
+    assert_conditions("2009-02-16 16 00:00:00", "2009-02-22 23:59:59", :last_week)
+  end                                                            
+                                                                 
+  def test_scope_with_next_week                                  
+    assert_conditions("2009-03-02 00:00:00", "2009-03-08 23:59:59", :next_week)
+  end                                                            
+                                                                 
+  def test_scope_with_this_month                                 
+    assert_conditions("2009-03-01 00:00:00", "2009-03-31 23:59:59", :this_month)
+  end                                                            
+                                                                 
+  def test_scope_with_last_month                                 
+    assert_conditions("2009-02-01 00:00:00", "2009-02-28 23:59:59", :last_month)
+  end                                                            
+                                                                 
+  def test_scope_with_next_month                                 
+    assert_conditions("2009-04-01 00:00:00", "2009-04-30 23:59:59", :next_month)
+  end                                                            
+
+  def test_scope_with_this_quarter                                         
+    assert_conditions("2009-01-01 00:00:00", "2009-03-31 23:59:59", :this_quarter)
+  end                                                            
+                                                                 
+  def test_scope_with_q1                                         
+    assert_conditions("2009-01-01 00:00:00", "2009-03-31 23:59:59", :q1)
+  end                                                            
+                                                                 
+  def test_scope_with_q2                                         
+    assert_conditions("2009-04-01 00:00:00", "2009-06-30 23:59:59", :q2)
+  end
+
+  def test_scope_with_q3
+    assert_conditions("2009-07-01 00:00:00", "2009-09-30 23:59:59", :q3)
+  end                                                            
+                                                                 
+  def test_scope_with_q4                                         
+    assert_conditions("2009-10-01 00:00:00", "2009-12-31 23:59:59", :q4)
+  end                                                            
+                                                                 
+  def test_scope_with_this_year                                  
+    assert_conditions("2009-01-01 00:00:00", "2009-12-31 23:59:59", :this_year)
+  end                                                            
+                                                                 
+  def test_scope_with_last_year                                  
+    assert_conditions("2008-01-01 00:00:00", "2008-12-31 23:59:59", :last_year)
+  end                                      
+                                           
+  def test_scope_with_next_year            
+    assert_conditions("2010-01-01 00:00:00", "2010-12-31 23:59:59", :next_year)
+  end
+
+  def test_scope_for_created_at_without_order
+    assert_nil Claim.created_at(:today).proxy_options[:order]
+  end
+
+  def test_scope_for_updated_at_with_order
+    assert_equal "name DESC", Claim.updated_at(:today).proxy_options[:order]
+  end
+
+  private
+
+    def assert_conditions(start_time, end_time, time_key)
+      assert_equal expected_options(start_time, end_time), Claim.created_at(time_key).proxy_options
+    end
+
+    def expected_options(start_time, end_time)
+      {:conditions => ["claims.created_at >= ? AND claims.created_at <= ?", 
+          Time.parse(start_time), Time.parse(end_time)]}
+    end
+end
+
+

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: named_scope_for_time_attr
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Thomas Baustert
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-11 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: newgem
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.0
+    version: 
+description: Provides the ActiveRecord helper method <tt>named_scope_for_time_attr</tt>.   Given the name of a time attribute of an ActiveRecord model  (e.g. <tt>created_at</tt> of <tt>Claim</tt>) it defines a correspondent named scope for easy access to an arbitrarily time range (scope).
+email: 
+- business@thomasbaustert.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+- Rakefile
+- init.rb
+- lib/named_scope_for_time_attr.rb
+- lib/named_scope_for_time_attr/named_scope_for_time_attr.rb
+- script/destroy
+- script/generate
+- test/test_helper.rb
+- test/test_named_scope_for_time_attr.rb
+has_rdoc: true
+homepage: "All information can be found here: http://nsfta.rubyforge.org/"
+post_install_message: PostInstall.txt
+rdoc_options: 
+- --main
+- README.rdoc
+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: nsfta
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Provides the ActiveRecord helper method <tt>named_scope_for_time_attr</tt>
+test_files: 
+- test/test_helper.rb
+- test/test_named_scope_for_time_attr.rb