monthify 0.0.1 → 0.0.2

data/README.md

@@ -1,6 +1,6 @@
 # Monthify
 
-TODO: Write a gem description
+Monthify provides a Month class in a similar style to Date and Time.
 
 ## Installation
 
@@ -18,7 +18,55 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Here are some example usages of the Month class.
+
+    this_month = Month.current
+    last_month = Month.containing(1.month.ago)
+
+    # all of these statements are true...
+    this_month > last_month
+    (last_month + 1.month) == this_month
+    last_month.next == this_month
+    this_month.previous == last_month
+
+    jan_2012 = Month.new(2012, 1)
+    # these are also true...
+    jan_2012.first_day == Date.new(2012, 1, 1)
+    jan_2012.last_day == Date.new(2012, 1, 31)
+    jan_2012.first_moment == jan_2012.first_date.beginning_of_day
+    jan_2012.last_moment == jan_2012.last_date.end_of_day
+
+### Conversions
+
+####Object#to_month
+
+    Date.today.to_month == Month.current
+    Time.now.to_month == Month.current
+
+####Month()
+
+This is equivalent to calling #to_month
+
+    Month(Date.today) == Month.current
+
+### ActiveRecord integration
+To treat a field in an ActiveRecord model like a month, do the following:
+
+1. Create a Date column on the table with the same name as the field you want
+2. Tell the model to serialize that field as a Month
+
+an example...
+
+    # in db/migrate/20121023060410_add_month_billed_to_statements.rb
+    
+    def up
+      add_column :statements, :month_billed, :date
+    end
+    
+
+    # in app/models/statement.rb
+
+    serialize :month_billed, Month
 
 ## Contributing
 

data/lib/monthify/core_ext/object.rb

@@ -1,6 +1,9 @@
 module Monthify
   module CoreExt
     module Object
+      # Converts the object to a month. Uses the same logic as Kernel::Month().
+      # Raises an ArgumentError if the object cannot be converted.
+      #@return [Month] the object converted to a Month
       def to_month
         ::Kernel::Month(self)
       end

data/lib/monthify/month.rb

@@ -6,73 +6,102 @@ module Monthify
 
     attr_reader :month, :year
 
+    #@return [Month] the current month
     def self.current
       today = Date.current
       new(today.year, today.month)
     end
 
+    #@param [Date, Time, #to_date] datish
+    #@return [Month] the month containing the given date
     def self.containing(datish)
       Month.new(datish.year, datish.month)
     end
 
+    # Used by ActiveRecord::Base.serialize
+    #@param [String] date_yaml the YAML for a date in the month
+    #@return [Month]
     def self.load(date_yaml)
       date = YAML.load(date_yaml)
       Month.containing(date)
     end
 
+    # Used by ActiveRecord::Base.serialize
+    #@param [Month] month
+    #@return [String] the YAML for the first date of the month
     def self.dump(month)
       YAML.dump(month.first_day)
     end
 
+    #@param [Integer] year the number of the year
+    #@param [Integer] month the number of the month
+    #@return [Month]
     def initialize(year, month)
       @year, @month = year, month
     end
 
+    #@return [Date] the first day of the month
     def first_day
       Date.new(year, month, 1)
     end
 
+    #@return [Date] the last day of the month
     def last_day
       first_day.end_of_month
     end
 
+    #@return [Time] the very beginning of the month
     def first_moment
       first_day.beginning_of_day
     end
 
+    #@return [Time] the very end of the month
     def last_moment
       last_day.end_of_day
     end
 
+    #@return [Month] the month preceeding this one
     def previous
       self - 1.month
     end
 
+    #@return [Month] the month following this one
     def next
       self + 1.month
     end
 
+    #@return [Range<Date, Date>] the range of dates in this month
     def date_range
       Range.new(first_day, last_day)
     end
 
+    #@return [Range<Time, Time>] the range of time in this month
     def time_range
       Range.new(first_moment, last_moment)
     end
 
+    #@param [Date, Time, #to_date] datish
+    #@return [Boolean] true if the month contains the date, false otherwise
     def contains?(datish)
       date = datish.to_date
       year == date.year && month == date.month
     end
 
+    # Adds the duration to the month
+    #@param [ActiveSupport::Duration] duration
+    #@return [Month]
     def +(duration)
       Month.containing(first_day + duration)
     end
 
+    # Subtracts the duration from the month
+    #@param [ActiveSupport::Duration] duration
+    #@return [Month]
     def -(duration)
       Month.containing(first_day - duration)
     end
 
+    #@!visibility private
     def <=>(other)
       if year == other.year
         month <=> other.month
@@ -81,10 +110,12 @@ module Monthify
       end
     end
 
+    #@!visibility private
     def hash
       [self.class, year, month].hash
     end
 
+    #@!visibility private
     def to_s
       "%d/%02d" % [year, month]
     end
@@ -92,13 +123,17 @@ module Monthify
 end
 
 module ::Kernel
-  def Month(convertee)
-    if convertee.is_a?(Month)
-      convertee
-    elsif convertee.respond_to?(:to_date)
-      Month.containing(convertee.to_date)
+  # Globally accessible method to convert an argument into a Month.
+  # If the argument cannot be converted, it raises an ArgumentError
+  #@param [Month, #to_date] object_to_convert the object to convert to a Month
+  #@return [Month] the given Month or the Month containing the given date
+  def Month(object_to_convert)
+    if object_to_convert.is_a?(Month)
+      object_to_convert
+    elsif object_to_convert.respond_to?(:to_date)
+      Month.containing(object_to_convert.to_date)
     else
-      raise ArgumentError, "Don't know how to convert #{convertee.inspect} to Month"
+      raise ArgumentError, "Don't know how to convert #{object_to_convert.inspect} to Month"
     end
   end
 end

data/lib/monthify/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monthify
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-24 00:00:00.000000000 Z
+date: 2012-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -78,3 +78,4 @@ test_files:
 - spec/lib/monthify/core_ext/object_spec.rb
 - spec/lib/monthify/month_spec.rb
 - spec/spec_helper.rb
+has_rdoc: