by_star 0.2.5

data/.gitignore

@@ -0,0 +1,2 @@
+tmp
+spec/fixtures/database.yml

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+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/README.markdown

@@ -0,0 +1,271 @@
+# by_*
+
+
+by_* (byStar) is a plugin that allows you to find ActiveRecord objects given certain date objects. This was originally crafted for only finding objects within a given month, but now has extended out to much more. It now supports finding objects for:
+
+* A given year
+* A given month
+* A given fortnight
+* A given week
+* A given weekend
+* A given day
+* The current weekend
+* The current work week
+* Between certain times
+* As of a certain time
+* Up to a certain time
+
+
+It also allows you to do nested finds on the records returned which I personally think is the coolest feature of the whole plugin:
+   
+    Post.by_month(1) do
+      { :include => "tags", :conditions => ["tags.name = ?", 'ruby'] }
+    end
+    
+If you're not using the standard `created_at` field: don't worry! I've covered that scenario too.
+
+
+## By Year (`by_year`)
+
+To find records based on a year you can pass it a two or four digit number:
+    
+    Post.by_year(09)
+    
+This will return all posts in 2009, whereas:
+
+    Post.by_year(99)
+
+will return all the posts in the year 1999.
+
+## By Month (`by_month`)
+
+If you know the number of the month you want:
+ 
+    Post.by_month(1)
+    
+This will return all posts in the first month (January) of the current year.
+
+If you like being verbose:
+
+    Post.by_month("January")
+
+This will return all posts created in January of the current year. 
+
+If you want to find all posts in January of last year just do 
+    
+    Post.by_month(1, :year => 2007)
+    
+or
+    
+    Post.by_month("January", :year => 2007)
+  
+This will perform a find using the column you've specified.
+
+If you have a Time object you can use it to find the posts:
+
+     Post.by_month(Time.local(2008, 11, 24))
+     
+This will find all the posts in November 2008.
+
+## By Fortnight (`by_fortnight`)
+
+Fortnight numbering starts at 0. The beginning of a fortnight is Monday, 12am.
+
+To find records from the current fortnight:
+    
+    Post.by_fortnight
+    
+To find records based on a fortnight, you can pass in a number (representing the fortnight number) or a time object:
+
+    Post.by_fortnight(18)
+   
+This will return all posts in the 18th fortnight of the current year.
+
+    Post.by_fortnight(18, :year => 2008)
+    
+This will return all posts in the 18th fortnight week of 2008.
+
+    Post.by_fortnight(Time.local(2008,1,1))
+    
+This will return all posts from the first fortnight of 2008.
+
+## By Week (`by_week`)
+
+Week numbering starts at 0. The beginning of a week is Monday, 12am.
+
+To find records from the current week:
+
+    Post.by_week
+    
+To find records based on a week, you can pass in a number (representing the week number) or a time object:
+
+    Post.by_week(36)
+   
+This will return all posts in the 36th week of the current year.
+
+    Post.by_week(36, :year => 2008)
+    
+This will return all posts in the 36th week of 2008.
+
+    Post.by_week(Time.local(2008,1,1))
+    
+This will return all posts from the first week of 2008.
+
+## By Weekend (`by_weekend`)
+
+If the time passed in (or the time now is a weekend) it will return posts from 12am Saturday to 11:59:59PM Sunday. If the time is a week day, it will show all posts for the coming weekend.
+
+    Post.by_weekend(Time.now)
+   
+## By Day (`by_day` or `today`)
+
+To find records for today:
+    
+    Post.by_day
+    Post.today
+    
+To find records for a certain day:
+
+    Post.by_day(Time.local(2008, 1, 1))
+
+You can also pass a string:
+    
+    Post.by_day("next tuesday")
+   
+This will return all posts for the given day.
+
+## Current Weekend (`by_current_weekend`)
+
+If you are currently in a weekend (between 3pm Friday and 3am Monday) this will find all records starting at 3pm the previous Friday up until 3am, Monday.
+
+If you are not in a weekend (between 3am Monday and 3pm Friday) this will find all records from the next Friday 3pm to the following Monday 3am.
+
+## Current Work Week (`by_current_work_week`)
+
+If you are currently in a work week (between 3am Monday and 3pm Friday) this will find all records in that range. If you are currently in a weekend (between 3pm Friday and 3am Monday) this will return all records in the upcoming work week.
+
+
+## Tomorrow (`tomorrow`)
+
+*This method has been shown to be shifty when passed a `Date` object, it is recommended that you pass it a `Time` object instead.*
+
+To find all posts from the day after the current date:
+
+    Post.tomorrow
+    
+To find all posts after a given Date or Time object:
+    
+    Post.tomorrow(Date.today + 2)
+    Post.tomorrow(Time.now + 5.days)
+    
+You can also pass a string:
+ 
+    Post.tomorrow("next tuesday")
+    
+## Yesterday (`yesterday`)
+
+*This method has been shown to be shifty when passed a `Date` object, it is recommended that you pass it a `Time` object instead.*
+
+To find all posts from the day before the current date:
+
+    Post.yesterday
+    
+To find all posts before a given Date or Time object:
+    
+    Post.yesterday(Date.today + 2)
+    Post.yesterday(Time.now + 5.days)
+    
+You can also pass a string:
+ 
+    Post.yesterday("next tuesday")
+    
+## Past (`past`)
+
+To find all posts before the current time:
+
+    Post.past
+
+To find all posts before certain time or date:
+
+    Post.past(Date.today + 2)
+    Post.past(Time.now + 5.days)
+    
+You can also pass a string:
+
+    Post.past("next tuesday")
+
+## Future (`future`)
+
+To find all posts after the current time:
+
+    Post.future
+
+To find all posts after certain time or date:
+
+    Post.future(Date.today + 2)
+    Post.future(Time.now + 5.days)
+    
+You can also pass a string:
+
+    Post.future("next tuesday")
+    
+## Between (`between`)
+
+To find records between two times:
+
+    Post.between(time1, time2)
+    
+Also works with dates:
+    
+    Post.between(date1, date2)
+    
+And with strings:
+
+    Post.between("last tuesday", "next wednesday")
+    
+## As of (`as_of_<dynamic>`)
+
+To find records as of a certain date up until the current time:
+    
+    Post.as_of_2_weeks_ago
+    
+This uses the Chronic "human mind reading" (read: it's really good at determining what time you mean using written English) library to work it out.
+
+## Up to (`up_to_<dynamic>`)
+
+To find records up to a certain time from the current time:
+
+    Post.up_to_6_weeks_from_now
+
+## Not using created_at? No worries!
+
+If your database uses something other than `created_at` for storing a timestamp, you can specify the field option like this:
+
+    Post.by_month("January", :field => :something_else)
+    
+All methods support this extra option.
+
+## Scoping the find
+
+All the `by_*` methods takes a block which will then scope the find based on the options passed into it. The supported options are the same options that are supported by `ActiveRecord::Base.find`:
+
+     Post.by_month(1) do
+       { :include => "tags", :conditions => ["tags.name = ?", 'ruby'] }
+     end
+## "Chronicable string"
+
+This means a string that can be parsed with the Chronic gem.
+     
+## Collaborators
+  
+Unfortunately I forget who exactly prompted me to write the plugin, but I would like to thank #rubyonrails for their support and the following people:
+
+* Mislav Marohnic
+* August Lilleas (leethal)
+* gte351s
+* Thomase Sinclair (anathematic)
+* The dude(s) & gal(s) who created Chronic
+     
+## Suggestions?
+
+If you have suggestions, please contact me at radarlistener@gmail.com

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "by_star"
+    gem.summary = %Q{ActiveRecord extension for easier date scopes and time ranges}
+    gem.description = %Q{ActiveRecord extension for easier date scopes and time ranges}
+    gem.email = "radarlistener@gmail.com"
+    gem.homepage = "http://github.com/radar/by_star"
+    gem.authors = ["Ryan Bigg", "Mislav Marohnić"]
+    gem.add_development_dependency "rspec"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "by_star #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.5

data/by_star.gemspec

@@ -0,0 +1,57 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{by_star}
+  s.version = "0.2.5"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ryan Bigg", "Mislav Marohni\304\207"]
+  s.date = %q{2009-10-15}
+  s.description = %q{ActiveRecord extension for easier date scopes and time ranges}
+  s.email = %q{radarlistener@gmail.com}
+  s.extra_rdoc_files = [
+    "README.markdown"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "by_star.gemspec",
+     "lib/by_star.rb",
+     "rails/init.rb",
+     "spec/by_star_spec.rb",
+     "spec/fixtures/models.rb",
+     "spec/fixtures/schema.rb",
+     "spec/spec_helper.rb",
+     "tmp/.gitignore"
+  ]
+  s.homepage = %q{http://github.com/radar/by_star}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{ActiveRecord extension for easier date scopes and time ranges}
+  s.test_files = [
+    "spec/by_star_spec.rb",
+     "spec/fixtures/models.rb",
+     "spec/fixtures/schema.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end

data/lib/by_star.rb

@@ -0,0 +1,316 @@
+require 'chronic'
+module ByStar
+  
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  module ClassMethods
+    # Examples:
+    #   by_year(2010)
+    #   # 2-digit year:
+    #   by_year(10)
+    #   # Time or Date object:
+    #   by_year(time)
+    #   # String:
+    #   by_year("2010")
+    def by_year(time=Time.zone.now.year, options={}, &block)
+      year = work_out_year(time)
+      
+      start_time = Time.utc(year, 1, 1)
+      end_time = start_time.end_of_year
+      by_star(start_time, end_time, options, &block)
+    rescue ArgumentError
+      raise ParseError, "Invalid arguments detected, year may possibly be outside of valid range (1902-2039). This is no longer a problem on Ruby versions > 1.8.7, so we recommend you upgrade to at least 1.8.7."
+    end
+    
+    # Examples:
+    #   by_month(1)
+    #   by_month("January")
+    #   by_month("January", :year => 2008)
+    #   by_month(time)
+    def by_month(time=Time.zone.now.month, options={}, &block)
+      time = Time.zone.now.month if time.nil?
+      year = options[:year] ||= Time.zone.now.year
+      # Work out what actual month is.
+      month = if time.is_a?(Numeric) && (1..12).include?(time)
+        time
+      elsif valid_time_or_date?(time)
+        year = time.year
+        time.month
+      elsif time.is_a?(String) && Date::MONTHNAMES.include?(time)
+        Date::MONTHNAMES.index(time)
+      else
+        raise ParseError, "Value is not an integer (between 1 and 12), time object or string (make sure you typed the name right)."
+      end
+      
+      start_time = Time.utc(year, month, 1)
+      end_time = start_time.end_of_month
+
+      by_star(start_time, end_time, options, &block)
+    end
+    
+    # Examples:
+    #   # 18th fortnight of 2004
+    #   Post.by_fortnight(18, :year => 2004)
+    def by_fortnight(time=Time.zone.now, options = {}, &block)
+      time = parse(time)
+      
+      # If options[:year] is passed in, use that year regardless.
+      year = work_out_year(options[:year]) if options[:year]
+      # If the first argument is a date or time, ask it for the year
+      year ||= time.year unless time.is_a?(Numeric)
+      # If the first argument is a fixnum, assume this year.
+      year ||= Time.zone.now.year
+      
+      # Dodgy!
+      # Surely there's a method in Rails to do this.
+      start_time = if valid_time_or_date?(time)
+        time.beginning_of_year + (time.strftime("%U").to_i).weeks
+      elsif time.is_a?(Numeric) && time <= 26
+        Time.utc(year, 1, 1) + ((time.to_i) * 2).weeks
+      else
+        raise ParseError, "by_fortnight takes only a Time or Date object, a Fixnum (less than or equal to 26) or a Chronicable string."
+      end
+      start_time = start_time.beginning_of_week
+      end_time = start_time + 2.weeks
+      by_star(start_time, end_time, options, &block)
+    end
+    
+    # Examples:
+    #   # 36th week
+    #   Post.by_week(36)
+    #   Post.by_week(36.54)
+    #   Post.by_week(36, :year => 2004)
+    #   Post.by_week(<Time object>)
+    #   Post.by_week(<Date object>)
+    #   Post.by_week("next tuesday")
+    def by_week(time=Time.zone.now, options = {}, &block)
+      time = parse(time)
+      
+      # If options[:year] is passed in, use that year regardless.
+      year = work_out_year(options[:year]) if options[:year]
+      # If the first argument is a date or time, ask it for the year
+      year ||= time.year unless time.is_a?(Numeric)
+      # If the first argument is a fixnum, assume this year.
+      year ||= Time.now.year
+      
+      # Dodgy!
+      # Surely there's a method in Rails to do this.
+      start_time = if valid_time_or_date?(time)
+        weeks = time.strftime("%U").to_i
+        time.beginning_of_year
+      elsif time.is_a?(Numeric) && time < 53
+        weeks = time.to_i
+        Time.utc(year, 1, 1)
+      else
+        raise ParseError, "by_week takes only a Time or Date object, a Fixnum (less than or equal to 53) or a Chronicable string."
+      end
+      start_time += weeks.weeks
+      end_time = start_time + 1.week
+      by_star(start_time, end_time, options, &block)
+    end
+    
+    
+    # Examples:
+    #    Post.by_weekend
+    #    Post.by_weekend(Time.now + 5.days)
+    #    Post.by_weekend(Date.today + 5)
+    #    Post.by_weekend("next tuesday")
+    def by_weekend(time=Time.zone.now, options = {}, &block)
+      time = parse(time)
+      start_time = time.beginning_of_weekend
+      by_star(start_time, (start_time + 1.day).end_of_day, options, &block)
+    end
+    
+    
+    # Examples:
+    # Post.by_current_weekend
+    def by_current_weekend(options = {}, &block)
+      time = Time.zone.now
+      # Friday, 3pm
+      start_time = time.beginning_of_weekend
+      # Monday, 3am
+      end_time = time.end_of_weekend
+      by_star(start_time, end_time, options, &block)
+    end
+    
+    # Examples:
+    # Post.by_current_work_week
+    def by_current_work_week(options = {}, &block)
+      time = Time.zone.now
+      # Monday, 3am
+      time = time + 1.week if time.wday == 6 || time.wday == 0
+      start_time = time.beginning_of_week + 3.hours
+      # Friday, 3pm
+      end_time = time.beginning_of_weekend
+      by_star(start_time, end_time, options, &block)
+    end
+    
+    
+    # Examples:
+    #   Post.by_day
+    #   Post.by_day(Time.yesterday)
+    #   Post.by_day("next tuesday")
+    def by_day(time = Time.zone.now, options = {}, &block)
+      time = parse(time)
+      by_star(time.beginning_of_day, time.end_of_day, options, &block)
+    end
+    alias_method :today, :by_day
+    
+    # Examples:
+    #   Post.yesterday
+    #   # 2 days ago:
+    #   Post.yesterday(Time.yesterday)
+    #   # day before next tuesday
+    #   Post.yesterday("next tuesday")
+    def yesterday(time = Time.zone.now, options = {}, &block)
+      time = parse(time)
+      by_day(time.advance(:days => -1), options, &block)
+    end
+    
+    # Examples:
+    #   Post.tomorrow
+    #   # 2 days from now:
+    #   Post.tomorrow(Time.tomorrow)
+    #   # day after next tuesday
+    #   Post.tomorrow("next tuesday")
+    def tomorrow(time = Time.zone.now, options = {}, &block)
+      time = parse(time)
+      by_day(time.advance(:days => 1), options, &block)
+    end
+    
+    # Scopes to records older than current or given time
+    # Post.past
+    # Post.past()
+    def past(time = Time.zone.now, options = {}, &block)
+      time = parse(time)
+      by_direction("<", time, options, &block)
+    end
+    
+    # Scopes to records newer than current or given time
+    def future(time = Time.zone.now, options = {}, &block)
+      time = parse(time)
+      by_direction(">", time, options, &block)
+    end
+    
+    private
+    
+      def by_direction(condition, time, options = {}, &block)
+        field = connection.quote_table_name(table_name)
+        field << "." << connection.quote_column_name(options[:field] || "created_at")
+        with_scope(:find => { :conditions => ["#{field} #{condition} ?", time.utc] }) do
+          if block_given?
+            with_scope(:find => block.call) do
+              find(:all)
+            end
+          else
+            find(:all)
+          end
+        end
+      end
+      
+      # scopes results between start_time and end_time
+      def by_star(start_time, end_time, options = {}, &block)
+        start_time = parse(start_time) 
+        end_time = parse(end_time)
+        
+        raise ParseError, "End time is before start time, searching like this will return no results." if end_time < start_time
+        
+        field = options[:field] || "created_at"
+        with_scope(:find => { :conditions => { field => start_time.utc..end_time.utc } }) do
+          if block_given?
+            with_scope(:find => block.call) do
+              find(:all)
+            end
+          else
+            find(:all)
+          end
+        end
+      end
+      
+      alias :between :by_star
+      public :between
+      
+      # This will work for the next 30 years (written in 2009)
+      def work_out_year(value)
+        case value
+        when 0..39
+          2000 + value
+        when 40..99
+          1900 + value
+        when nil
+          Time.zone.now.year
+        else
+          # We may be passed something that's not a straight out integer
+          # These things include: BigDecimals, Floats and Strings.
+          value.to_i
+        end
+      end
+      
+      # Checks if the object is a Time, Date or TimeWithZone object.
+      def valid_time_or_date?(value)
+        value.is_a?(Time) || value.is_a?(Date) || value.is_a?(ActiveSupport::TimeWithZone)
+      end
+      
+      def parse(object)
+        object = case object.class.to_s
+        when "NilClass"
+          o = Time.zone.now
+        when "String"
+          o = object
+          Chronic.parse(object, :now => Time.zone.now)
+        when "Date"
+          object.to_time(:utc)
+        else
+          object
+        end
+        raise ParseError, "Chronic couldn't work out #{o.inspect}; please be more precise." if object.nil?
+        object
+      end
+      
+      def method_missing(method, *args)
+        if method.to_s =~ /^(as_of|up_to)_(.+)$/
+          method = $1
+          expr = $2.humanize
+          unless time = parse(expr)
+            raise ParseError, "Chronic couldn't work out #{expr.inspect}; please be more precise."
+          end
+          
+          reference = args.first || Time.now
+          
+          if "as_of" == method
+            between(time, reference)
+          else
+            between(reference, time)
+          end
+        else
+          super
+        end
+      end
+  end
+  
+  class ParseError < Exception; end
+  class MonthNotFound < Exception; end
+end
+
+class Time
+  def beginning_of_weekend
+    friday = case self.wday
+    when 0
+      self.end_of_week.beginning_of_day.advance(:days => -2) 
+    when 5
+      self.beginning_of_day
+    else
+      self.beginning_of_week.advance(:days => 4)
+    end
+    # 3pm, Friday.
+    (friday + 15.hours)
+  end
+  
+  def end_of_weekend
+    # 3am, Monday.
+    # LOL I CHEATED.
+    beginning_of_weekend + 3.days - 12.hours
+  end
+end