mongoid-historicals 0.1.1 → 0.1.2

data/README.md

@@ -1,5 +1,40 @@
 Mongoid Historicals
 ===================
 
-Record a snapshot of current values to reference later as historical values.  Useful for showing changes in values over time.
+Record a snapshot of current values to reference later as historical values.
+
+
+Installation
+------------
+
+Add to your Gemfile
+
+    gem 'mongoid-historicals', :require => 'mongoid/historicals'
+
+
+Usage
+-----
+
+Here is an example of how to track the week-to-week score for the players in my fictional MMORPGFPS:
+
+    class Player
+      include Mongoid::Document
+      include Mongoid::Historicals
+
+      field :username, type: String
+      field :score,    type: Integer
+
+      historicals :score, :max => 52, :frequency => :weekly
+    end
+
+In a cron task, I could run the following every Sunday before midnight:
+
+    Player.all.each do |player|
+      player.record!
+    end
+
+Then, I could show each player's historical score like this:
+
+    <h2>Your Current Score: <%= @player.score %></h2>
+    <p>Your Score Last Week: <%= @player.historical(:score, 1.week.ago) %> / Difference: <%= @player.historical_difference(:score, 1.week.ago) %></p>
 

data/lib/mongoid/historicals/version.rb

@@ -1,7 +1,7 @@
 module Mongoid
   module Historicals
 
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
 
   end
 end

data/lib/mongoid/historicals.rb

@@ -14,8 +14,11 @@ module Mongoid
       class_attribute :historical_options
     end
 
-    # Save the current values for historicals by label
+    # Save the current values as a historical record
     #
+    # @param [String, #to_datetime] label The label as a String, Symbol or DateTime that the historical record will be saved as. If you pass a DateTime object, it
+    #   will use the <tt>:frequency</tt> option from historicals to save as a date/time.
+    # @return [Record] the historical record that is saved
     def record!(label = nil)
       label ||= Time.now
       record = historical(label) || self.historicals.build(:'_label' => labelize(label))
@@ -29,24 +32,72 @@ module Mongoid
       record
     end
 
-    def historical(label)
-      self.historicals.where(:'_label' => labelize(label)).first
+    # Retrieve the historical record or a single attribute value from the 
+    # specified label. If only one argument is given, it will return
+    # the entire record with that label. If two arguments are given, the 
+    # first argument will specify the attribute and the second argument is the
+    # label to use.
+    #
+    # @param [String, #to_datetime] attr_or_label If only one argument is given, 
+    #   this is the <tt>label</tt> for the record to be returned. If two arguments 
+    #   are given, this should be the symbol of the attribute whose value should 
+    #   be returned.
+    # @return With one argument given, the historical record or nil if none 
+    #   exists. With two arguments given, it should return the value of the 
+    #   requested attribute for the specified label.
+    def historical(attr_or_label, label = nil)
+      if label.nil?
+        self.historicals.where(:'_label' => labelize(attr_or_label)).first
+      else
+        record = self.historicals.where(:'_label' => labelize(label)).first
+
+        if record
+          record[attr_or_label]
+        else
+          nil
+        end
+      end
     end
 
+    # Return the difference between the current value of the attribute and the value of attribute from the 
+    # <tt>label</tt> historical record.
+    #
+    # @param [Symbol] attr The attribute on which you are calculating the difference
+    # @param [String, Symbol, #to_datetime] label The label as a String, Symbol or Datetime for the historical record against which you are comparing
+    # @param [Hash] options
+    # @option options [Object] :default The value you want returned if there is no historical for comparison (default: 0)
     def historical_difference(attr, label, options = {})
       opts = {
         default: 0
       }.merge(options)
 
-      record = historical(labelize(label))
-
       begin
-        self[attr] - record[attr]
+        self[attr] - historical(attr, label)
       rescue # Pokemon exception handling, but actually seems appropriate here
         opts[:default]
       end
     end
 
+    module ClassMethods
+
+      # This model should record historical values for the specified
+      # attributes.
+      #
+      # @overload historicals(*attrs, options = {})
+      #   @param [Array] attrs The symbol(s) for the attributes for which you want to store historicals
+      #   @param [Hash] options
+      #   @option options [Integer] :max The maximum number of entries to store (default: unlimited)
+      #   @option options [:monthly,:weekly,:daily] :frequency The frequency to use for DateTime labels (default: :daily)
+      def historicals(*attrs)
+        options = attrs.extract_options!
+        options[:max] ||= nil
+        options[:frequency] ||= :daily
+
+        self.historical_options = options
+        self.historical_attributes = attrs
+      end
+    end
+
     private
 
       def labelize(label)
@@ -79,25 +130,5 @@ module Mongoid
           end
         end
       end
-
-    module ClassMethods
-
-      # This model should record historical values for the specified
-      # attributes.
-      #
-      # Options:
-      # 
-      #   <tt>max</tt>: The maximum number of entries to store (default: none)
-      #   <tt>frequency</tt>: :monthly, :weekly, or :daily (default: :daily)
-      #
-      def historicals(*attrs)
-        options = attrs.extract_options!
-        options[:max] ||= nil
-        options[:frequency] ||= :daily
-
-        self.historical_options = options
-        self.historical_attributes = attrs
-      end
-    end
   end
 end

data/test/historicals_test.rb

@@ -95,18 +95,38 @@ describe Mongoid::Historicals do
       @player.record!('test')
     end
 
-    describe "when record exists" do
-      it "should return record" do
-        @record = @player.historical('test')
-        @record.must_be_instance_of(Mongoid::Historicals::Record)
-        @record._label.must_equal 'test'
+    describe "with one argument" do
+      describe "when record exists" do
+        it "should return record with specified label" do
+          @record = @player.historical('test')
+          @record.must_be_instance_of(Mongoid::Historicals::Record)
+          @record._label.must_equal 'test'
+        end
+      end
+
+      describe "when record does not exist" do
+        it "should return nil" do
+          @record = @player.historical('unknown-label')
+          @record.must_equal nil
+        end
       end
     end
 
-    describe "when record does not exist" do
-      it "should return nil" do
-        @record = @player.historical('unknown-label')
-        @record.must_equal nil
+    describe "with two arguments" do
+      it "should return historical value (from label) of specified attribute" do
+        @player.historical(:score, 'test').must_equal 95.0
+      end
+
+      describe "when record does not exist" do
+        it "should return nil" do
+          @player.historical(:score, 'invalid').must_equal nil
+        end
+      end
+
+      describe "when attribute does not exist" do
+        it "should return nil" do
+          @player.historical(:invalid, 'test').must_equal nil
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid-historicals
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -99,3 +99,4 @@ signing_key:
 specification_version: 3
 summary: ''
 test_files: []
+has_rdoc: