temporal_scopes 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01054fa8697a5d6a48d6cd36198905e919911a2e
-  data.tar.gz: 447d77b095f5c0d98c4972ab4debf32770e85c12
+  metadata.gz: a0bb59fb20ec57703464efa1db45f23340de3450
+  data.tar.gz: baeec6001c3138410bd94561be1339292948b4fb
 SHA512:
-  metadata.gz: 395a9c350971e89678b547a9b6397eedc9817637f4c4f5ec98a299352e6acd95eee54ff9fd3723d63fb15dd367da221445b8d7e6b6e55137eca01a97a76560a5
-  data.tar.gz: aa871fb961337b880c652c9aef1507a094904bf5dd85d2ed3d73bf311e193a112dced1e6d392ca4a6876362d8a4da78f74b54c3b36e76832b8ac59dd3f0d9117
+  metadata.gz: 3936bb8540a87a2f6aff81483a0e6ee5e3fa623466bb5c7c426097342280e74add1ff5b92b66c14c95f99b114d077ebade22b186b106ff7d27560c7c7cdc4c51
+  data.tar.gz: ff2003aff6d0c39d4a0fef33490dc95e73da1d2a062596b60ba6fb74e9d3c8f9c597626f2c10c457b2bf9efaee8711848c35ebb5454433b5542e8c1a312796d3

data/README.md

@@ -1,4 +1,4 @@
-# TemporalScopes [![Build Status](https://travis-ci.org/fiedl/temporal_scopes.svg?branch=master)](https://travis-ci.org/fiedl/temporal_scopes)
+# TemporalScopes [![Build Status](https://travis-ci.org/fiedl/temporal_scopes.svg?branch=master)](https://travis-ci.org/fiedl/temporal_scopes) [![Gem Version](https://badge.fury.io/rb/temporal_scopes.svg)](http://badge.fury.io/rb/temporal_scopes)
 
 Providing temporal scopes for an ActiveRecord model to allow queries by time. For example, `MyModel.now.where(...)`, `my_model.archive`, `MyModel.past.where(...)`.
 
@@ -50,7 +50,9 @@ Further [documentation can be found on rubydoc.info](http://rubydoc.info/github/
 
 ### Caveats
 
+* This gem requires Rails 4.
 * There is only one `valid_from` and one `valid_to` time per object. Therefore, you can't keep track of first archiving an object and later un-archiving it. Un-archiving an object loses the information of first archiving it.
+* Currently, the future is not handled (`Article.future` and `article.archive at: 1.hour.from.now` do not work.) But this is planned to be implemented in the future.
 
 ## Installation
 

data/lib/temporal_scopes/has_temporal_scopes.rb

@@ -3,38 +3,125 @@ require 'active_record'
 module TemporalScopes
   module HasTemporalScopes
     
+    # Adds scopes and methods for handing temporal filtering.
+    # 
+    # ## Make an `ActiveRecord` have temporal scopes
+    #
+    #     class Article < ActiveRecord::Base
+    #       has_temporal_scopes
+    #       
+    #     end
+    # 
+    # ## Archive an object
+    # 
+    #     current_article = Article.create(title: 'My new article', body: 'Lorem ipsum')
+    #     
+    #     past_article = Article.create(title: 'My new article', body: 'Lorem ipsum')
+    #     past_article.archive
+    #     
+    #     # or provide a datetime:
+    #     past_article.archive at: 1.hour.ago
+    # 
+    # ## Use temporal scopes for filtering
+    # 
+    #     Article.now                          #  => [current_article]
+    #     Article.past                         #  => [past_article]
+    #     Article.with_past                    #  => [current_article, past_article]
+    # 
+    # Note that the **default scope** is set to `now`.
+    # 
+    #     Article.all                          #  => [current_article]
+    #     Article.now                          #  => [current_article]
+    #     Article.with_past                    #  => [current_article, past_article]
+    #     Article.without_temporal_condition   #  => [current_article, past_article]
+    #
     def has_temporal_scopes
       
-      scope :without_temporal_condition, -> { 
-        relation = unscope(where: [:valid_from, :valid_to]) 
-        relation.where_values.delete_if { |query| query.to_sql.include?("\"valid_from\"") || query.to_sql.include?("\"valid_to\"") }
-        relation
-      }
-      
-      scope :now, -> { 
-        without_temporal_condition
-        .where(arel_table[:valid_from].eq(nil).or(arel_table[:valid_from].lteq(Time.zone.now)))
-        .where(arel_table[:valid_to].eq(nil).or(arel_table[:valid_to].gteq(Time.zone.now)))
-      }
-      scope :past, -> { without_temporal_condition.where('valid_to < ?', Time.zone.now) }
-      scope :with_past, -> { without_temporal_condition }
-      
       default_scope { now }
       
       extend ClassMethods
       include InstanceMethods
     end
     
+    # The following class methods and scopes are added to 
+    # `ActiveRecord::Base` classes that have been called
+    # `has_temporal_scopes` on.
+    #
     module ClassMethods
+
+      # Removes temporal conditions from the query.
+      #
+      # @example
+      #     Article.where(valid_to: 10.days.ago..1.day.ago)                             # => []  (due to default scope.)
+      #     Article.without_temporal_condition.where(valid_to: 10.days.ago..1.day.ago)  # returns the desired articles.
+      #
+      # @return [ActiveRecord::Relation] the relation without temporal conditions on `valid_from` and `valid_to`.
+      #
+      def without_temporal_condition
+        relation = unscope(where: [:valid_from, :valid_to]) 
+        relation.where_values.delete_if { |query| query.to_sql.include?("\"valid_from\"") || query.to_sql.include?("\"valid_to\"") } if relation && relation.where_values
+        relation
+      end
+
+      # Filters for only current objects.
+      #
+      # This is the default scope.
+      #
+      # @return [ActiveRecord::Relation] only current objects.
+      #
+      def now
+        without_temporal_condition
+        .where(arel_table[:valid_from].eq(nil).or(arel_table[:valid_from].lteq(Time.zone.now)))
+        .where(arel_table[:valid_to].eq(nil).or(arel_table[:valid_to].gteq(Time.zone.now)))
+      end
+      
+      # Filters for only past objects.
+      #
+      # @return [ActiveRecord::Relation] only past objects.
+      #
+      # @example Getting only archived articles by an author.
+      #     author.articles.past
+      #
+      def past
+        without_temporal_condition.where('valid_to < ?', Time.zone.now)
+      end
+      
+      # Removes the filters such that past and present
+      # objects are returned.
+      # 
+      # @return [ActiveRecord::Relation] past and current objects.
+      #
+      def with_past
+        without_temporal_condition
+      end
+
     end
-    
+
+    # The following instance methods are added to 
+    # `ActiveRecord::Base` objects, which classes have 
+    # been called `has_temporal_scopes` on.
+    #
     module InstanceMethods
       
+      # Archives an object, that is, makes it a past object.
+      # 
+      # @param params [Hash] a hash of parameters.
+      # @option params :at [DateTime] (Time.zonw.now) when to archive the object, i.e. the time when the present object becomes a past object, i.e. expires.
+      #
+      # @return [ActiveRecord::Base] the archived object.
+      #
+      # @example Archiving an object now.
+      #     article.archive
+      #
+      # @example Archiving an object with effect 4 hours ago.
+      #     article.archive at: 4.hours.ago
+      # 
       def archive(params = {})
         unless self.valid_to
           archive_at = params[:at] || Time.zone.now
           update_attribute(:valid_to, archive_at)
         end
+        return self
       end
 
     end

data/lib/temporal_scopes/version.rb

@@ -1,3 +1,3 @@
 module TemporalScopes
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: temporal_scopes
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Sebastian Fiedlschuster