date_scopes 0.1

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+*.gem
+.bundle
+.yardoc
+doc

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.rvmrc

@@ -0,0 +1 @@
+rvm gemset use date_scopes

data/Gemfile

@@ -0,0 +1,8 @@
+source :gemcutter
+
+# Specify your gem's dependencies in date_scope.gemspec
+gemspec
+
+group :test do
+  gem 'autowatchr', :git => 'https://github.com/SFEley/autowatchr.git'
+end

data/Gemfile.lock

@@ -0,0 +1,54 @@
+GIT
+  remote: https://github.com/SFEley/autowatchr.git
+  revision: 2b2d80e0e8f4075d278adbb1373cad854d35a454
+  specs:
+    autowatchr (0.1.4)
+      watchr
+
+PATH
+  remote: .
+  specs:
+    date_scopes (0.0.1)
+      activerecord (~> 3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.3)
+    arel (2.0.6)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    i18n (0.5.0)
+    rspec (2.2.0)
+      rspec-core (~> 2.2)
+      rspec-expectations (~> 2.2)
+      rspec-mocks (~> 2.2)
+    rspec-core (2.2.1)
+    rspec-expectations (2.2.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.2.0)
+    sqlite3-ruby (1.3.2)
+    timecop (0.3.5)
+    tzinfo (0.3.23)
+    watchr (0.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (~> 3)
+  autowatchr!
+  bundler (>= 1.0.0)
+  date_scopes!
+  rspec (~> 2)
+  sqlite3-ruby
+  timecop

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 ThroughTheNet
+
+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,97 @@
+#Date_Scopes - an ActiveRecord extension for automatic date-based scopes
+
+**Homepage/Github**:  [github.com/ThroughTheNet/date_scopes](https://github.com/ThroughTheNet/date_scopes)  
+**Documentation**:    [rubydoc.info](http://rubydoc.info/gems/date_scopes/0.1/frames)  
+**Author**:           Jonathan Davies ([ThroughTheNet](http://throughthnet.com))  
+**Contact**:          [info@throughthenet.com](mailto:info@throughthenet.com)  
+**License**:          [MIT License](http://opensource.org/licenses/mit-license.php)  
+**Version**:          0.1  
+**Released**:         December 2nd 2010
+
+##Description
+
+
+Date_Scopes is a rubygem that adds a simple macro, {DateScopes::ClassMethods#has_date_scopes has_date_scopes} to ActiveRecord. When used it adds a number of convinience scopes to your models relating to a whether a particular date field on that model is in the past or future. It also has other handy features.
+
+Note that it does *not* depend on the whole of Rails, but is a pure ActiveRecord extension. As such it can be used wherever you use ActiveRecord, be it in Sinatra or whatever other mad thing you've cooked up.
+
+##Example Use Case
+
+Say you have a model `Post` in your blog app. You want to be able to write your posts and save them, but not have them appear on the site until a certain time in the future, when they should automatically appear.
+Perhaps you have offers or coupons that need to expire after a certain date, or maybe some task has a deadline by which it must be completed.
+This gem will neaten up your model code whenever your model instances need to be divided into to groups: those of them whos date field is before `Time.now`, and those whos date field is after `Time.now`
+
+##Functionality
+
+###Dynamic Scopes
+
+Assuming that the model has a datetime field called `published_at`, one can simply call the {DateScopes::ClassMethods#has_date_scopes has_date_scopes} method in the model defintion like so:
+
+    class Post < ActiveRecord::Base
+      has_date_scopes
+    end
+    
+This will create the following scopes on the post class
+
+    published
+    
+    unpublished
+    nonpublished
+    non_published
+    not_published
+    
+The first scope will return all `Post` records whose `published_at` field is in the past.
+All the other scopes will return the `Post` records whose `published_at` field is in the future.
+The duplication of the negative scopes is just in the interests of natural looking code.
+Note that any records whose `published_at` field exactly equals `Time.now` will fall into both scopes.
+Any record with a `nil` `published_at` field will be in the negative scopes, `unpublished` and so on.
+
+###Virtual Accessors
+
+Use of the macro also creates an automatic virtual getter/setter pair, allowing you to interact with the `published_at` column as if it were a boolean column called `published` in that it defines the following methods:
+
+    published
+    published?
+    
+    published=
+    
+The first two simply return true or false depending on whether the field is in the past or future, much the same as the scopes described above. The second is more interesting, in that it accepts a boolean.
+If it is passed `true`, it will set the `published_at` column to `Time.now`. If it is passed `false` it sets `published_at` to `nil`. Again it is obvious how this complements the scopes.
+
+These virtual boolean setters/getters function exactly like real ones, so feel free to use them in your forms and such, in exactly the same way as you would as if you had a real boolean column in your schema.
+This can be used to keep a record of when a user set a boolean as true, for example if your date column is `deleted_at` you could use the `deleted=` virtual setter in a form so the user can 'delete' the record easily, and you will have a record in the `deleted_at` column of when this change took place.
+Obviously one could then use the `non_deleted` scope to hide those records from the index action etc.
+
+##Customization
+
+The only option accepted by {DateScopes::ClassMethods#has_date_scopes has_date_scopes} currently is `column` which simply changes the field name used and the corresponding dynamic scopes/setters/getters from its default of `:published`.
+For example if one had a model `Order` with a `DateTime` column called `filled_at` one could define it like this:
+
+    class Order < ActiveRecord::Base
+      has_date_scopes :column => :filled
+    end
+    
+Then the `Order` class would have the following scopes:
+
+    filled
+    
+    unfilled
+    nonfilled
+    non_published
+    not_published
+    
+**NOTE**: The column option actually takes the verb that will form part of the various dynamic methods, and then adds `_at` to that name to find the name of the database column. In future it should be made to accept either but the current interface will not be broken. If the correct database column for the `:column` option is not found, the macro method will raise an exception.
+
+##Contributing
+
+This it github. You know the score!
+
+1. Fork
+2. Hack
+3. Push
+4. Pull
+
+Tests are set up with Rspec2, `bundle exec watchr spec.watchr` is reccommended for continous testing goodness.
+
+## Copyright
+Copyright (c) 2010 ThroughTheNet. MIT Licensed. See the {file:LICENSE} file

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/date_scopes.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/date_scopes/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "date_scopes"
+  s.version     = DateScopes::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Jonathan Davies', 'ThroughTheNet']
+  s.email       = ['info@throughthenet.com']
+  s.license     = "MIT"
+  s.homepage    = "https://github.com/ThroughTheNet/date_scopes"
+  s.summary     = "An ActiveRecord extension for automatic date-based scopes"
+  s.description = "Adds a simple macro, has_date_scopes to ActiveRecord. When used it adds a number of convinience scopes to your models relating to a whether a particular date field on that model is in the past or future. It also has other handy features."
+
+  s.required_rubygems_version = ">= 1.3.6"
+
+  s.add_dependency "activerecord", "~> 3"
+  
+  s.add_development_dependency "bundler", ">= 1.0.0"
+  s.add_development_dependency "rspec", "~> 2"
+  s.add_development_dependency 'timecop', '>= 0'
+  s.add_development_dependency 'sqlite3-ruby', '>= 0'
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/lib/date_scopes.rb

@@ -0,0 +1,69 @@
+require 'active_record'
+
+module DateScopes
+  
+  module ClassMethods
+  
+    # Adds a number of dynamic scopes and a virtual accessor to your model.
+    # Functionality is detailed more fully in the {file:README.markdown README} for this gem, but a brief demo is given here:
+    # @example
+    #    class Post < ActiveRecord::Base
+    #      has_date_scopes
+    #    end
+    #
+    #    Post.published                  #posts with published_at before Time.now
+    #    Post.unpublished                #posts with published_at after Time.now
+    #    post = Post.new
+    #    post.published = true           #virtual setter, sets published_at to Time.now
+    #    post.published_at == Time.now   #true
+    #    post.published? == true         #true
+    #    post.published = false          #virtual setter, sets published_at to nil
+    #    post.published_at.nil?          #true
+    # @param [Hash] opts The options
+    # @option opts [Symbol, String] :column The verb that will be used to form the names of the scopes, and corresponds to a database column (if :column is `deleted` then there must be a database column `deleted_at`.) Defaults to `published` and a corresponding database column `published_at`
+    # @raise [ActiveRecordError] An exception will be raised if the required column is not present, telling you the name of the column it expects.
+
+    def has_date_scopes(options = {})
+      options.to_options!.reverse_merge! :column => 'published'
+      column_name = "#{options[:column]}_at"
+      
+      raise new ActiveRecordError("Could not find the #{column_name} column on the #{table_name} table") unless column_names.include? column_name
+      
+      on_scope_sql = "#{table_name}.#{column_name} <= ?"
+      
+      un_scope_sql = "#{table_name}.#{column_name} >= ? OR #{table_name}.#{column_name} IS NULL"
+      
+      scope options[:column], lambda { where(on_scope_sql, Time.now) }
+      %w{un non non_ not_}.each do |prefix|
+        scope prefix+options[:column].to_s, lambda { where(un_scope_sql, Time.now) }
+      end
+      
+      define_method options[:column].to_s+'=' do |value|
+        if value && !self[column_name]
+
+          self[column_name] = Time.now
+
+        elsif !value
+
+          self[column_name] = nil
+        end
+      end
+      
+      define_method options[:column] do
+        return false unless time = self[column_name]
+        time <= Time.now
+      end
+      alias_method options[:column].to_s+'?', options[:column]
+      
+    end
+  end
+  
+  private
+  
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+  
+end
+
+ActiveRecord::Base.send(:include, DateScopes)

data/lib/date_scopes/version.rb

@@ -0,0 +1,3 @@
+module DateScopes
+  VERSION = "0.1"
+end

data/spec.watchr

@@ -0,0 +1,8 @@
+require 'stringio'
+require 'autowatchr'
+
+Autowatchr.new(self) do |config|
+  config.test_dir = 'spec'
+  config.test_re = "^spec/.*_spec\\.rb$"
+  config.test_file = '%s_spec.rb'
+end

data/spec/date_scopes_spec.rb

@@ -0,0 +1,122 @@
+require 'spec_helper'
+
+class Post < ActiveRecord::Base;end
+class Page < ActiveRecord::Base;end
+class Empty < ActiveRecord::Base;end
+
+describe DateScopes do
+  
+  context 'with default options' do
+    before(:all) {Post.class_exec {has_date_scopes}}
+    
+    it 'has un-scopes' do
+      Post.scopes.should include(:unpublished)
+      Post.scopes.should include(:nonpublished)
+      Post.scopes.should include(:non_published)
+      Post.scopes.should include(:not_published)
+    end
+    
+    it 'has on-scope' do
+      Post.scopes.should include(:published)
+    end
+    
+    it "accepts true to boolean setter and sets as the time" do
+      Timecop.freeze do
+        post = Post.new
+        post.published = true
+        post.published_at.should == Time.now
+      end
+    end
+    
+    it "doesn't reset the time with a boolean when time is already set" do
+      Timecop.freeze
+      post = Post.new
+      post.published = true
+      post.save
+      time = post.published_at
+      Timecop.return
+      post.update_attributes :published => true
+      time.should == post.published_at
+    end
+    
+    it "accepts false to boolean setter and sets column as nil" do
+      post = Post.new
+      post.published_at = Time.now
+      post.published_at.should_not be_nil
+      post.published = false
+      post.published_at.should be_nil
+    end
+    
+    context 'when published_at is in the past' do
+      before(:all) {@post = Post.create(:published_at => Time.now - 10.minutes)}
+      
+      it 'is in the published scope' do
+        Post.published.should include(@post)
+      end
+      
+      it 'is not in the unpublished scope' do
+        Post.unpublished.should_not include(@post)
+      end
+      
+      it "is published" do
+        @post.should be_published
+      end
+      
+    end
+    
+    context 'when published_at is in the future' do
+      before(:all) {@post = Post.create :published_at => Time.now + 10.minutes}
+      
+      it "is in the unpublished scope" do
+        Post.unpublished.should include(@post)
+      end
+      
+      it "is not in the published scope" do
+        Post.published.should_not include(@post)
+      end
+      
+      it "is not published" do
+        @post.should_not be_published
+      end
+      
+    end
+    
+    context 'when published_at is empty' do
+      before(:all) {@post = Post.create(:published_at => nil)}
+      
+      it "is in the unpublished scope" do
+        Post.unpublished.should include(@post)
+      end
+      
+      it "is not in the published scope" do
+        Post.published.should_not include(@post)
+      end
+      
+      it "is not published" do
+        @post.should_not be_published
+      end
+    end
+    
+    context 'with custom column name' do
+      before(:all) {Page.class_exec{has_date_scopes :column => :sold}}
+      
+      it 'has un-scopes' do
+        Page.scopes.should include(:unsold)
+        Page.scopes.should include(:nonsold)
+        Page.scopes.should include(:non_sold)
+        Page.scopes.should include(:not_sold)
+      end
+      
+      it 'has on-scope' do
+        Page.scopes.should include(:sold)
+      end
+    end
+    
+    context 'when missing the required column' do
+      it "raises an exception" do
+        lambda {Empty.class_exec{has_date_scopes(:column => :foobar)}}.should raise_error
+      end
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'bundler'
+
+ENV["RAILS_ENV"] ||= 'test'
+Bundler.require(:default, :development)
+
+ActiveRecord::Base.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => 'spec/support/test.sqlite3'
+)

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification 
+name: date_scopes
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Jonathan Davies
+- ThroughTheNet
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-02 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 3
+        version: "3"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 2
+        version: "2"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: timecop
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: Adds a simple macro, has_date_scopes to ActiveRecord. When used it adds a number of convinience scopes to your models relating to a whether a particular date field on that model is in the past or future. It also has other handy features.
+email: 
+- info@throughthenet.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.markdown
+- Rakefile
+- date_scopes.gemspec
+- lib/date_scopes.rb
+- lib/date_scopes/version.rb
+- spec.watchr
+- spec/date_scopes_spec.rb
+- spec/spec_helper.rb
+- spec/support/test.sqlite3
+has_rdoc: true
+homepage: https://github.com/ThroughTheNet/date_scopes
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: An ActiveRecord extension for automatic date-based scopes
+test_files: []
+