monthify 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Monthify
2
2
 
3
- TODO: Write a gem description
3
+ Monthify provides a Month class in a similar style to Date and Time.
4
4
 
5
5
  ## Installation
6
6
 
@@ -18,7 +18,55 @@ Or install it yourself as:
18
18
 
19
19
  ## Usage
20
20
 
21
- TODO: Write usage instructions here
21
+ Here are some example usages of the Month class.
22
+
23
+ this_month = Month.current
24
+ last_month = Month.containing(1.month.ago)
25
+
26
+ # all of these statements are true...
27
+ this_month > last_month
28
+ (last_month + 1.month) == this_month
29
+ last_month.next == this_month
30
+ this_month.previous == last_month
31
+
32
+ jan_2012 = Month.new(2012, 1)
33
+ # these are also true...
34
+ jan_2012.first_day == Date.new(2012, 1, 1)
35
+ jan_2012.last_day == Date.new(2012, 1, 31)
36
+ jan_2012.first_moment == jan_2012.first_date.beginning_of_day
37
+ jan_2012.last_moment == jan_2012.last_date.end_of_day
38
+
39
+ ### Conversions
40
+
41
+ ####Object#to_month
42
+
43
+ Date.today.to_month == Month.current
44
+ Time.now.to_month == Month.current
45
+
46
+ ####Month()
47
+
48
+ This is equivalent to calling #to_month
49
+
50
+ Month(Date.today) == Month.current
51
+
52
+ ### ActiveRecord integration
53
+ To treat a field in an ActiveRecord model like a month, do the following:
54
+
55
+ 1. Create a Date column on the table with the same name as the field you want
56
+ 2. Tell the model to serialize that field as a Month
57
+
58
+ an example...
59
+
60
+ # in db/migrate/20121023060410_add_month_billed_to_statements.rb
61
+
62
+ def up
63
+ add_column :statements, :month_billed, :date
64
+ end
65
+
66
+
67
+ # in app/models/statement.rb
68
+
69
+ serialize :month_billed, Month
22
70
 
23
71
  ## Contributing
24
72
 
@@ -1,6 +1,9 @@
1
1
  module Monthify
2
2
  module CoreExt
3
3
  module Object
4
+ # Converts the object to a month. Uses the same logic as Kernel::Month().
5
+ # Raises an ArgumentError if the object cannot be converted.
6
+ #@return [Month] the object converted to a Month
4
7
  def to_month
5
8
  ::Kernel::Month(self)
6
9
  end
@@ -6,73 +6,102 @@ module Monthify
6
6
 
7
7
  attr_reader :month, :year
8
8
 
9
+ #@return [Month] the current month
9
10
  def self.current
10
11
  today = Date.current
11
12
  new(today.year, today.month)
12
13
  end
13
14
 
15
+ #@param [Date, Time, #to_date] datish
16
+ #@return [Month] the month containing the given date
14
17
  def self.containing(datish)
15
18
  Month.new(datish.year, datish.month)
16
19
  end
17
20
 
21
+ # Used by ActiveRecord::Base.serialize
22
+ #@param [String] date_yaml the YAML for a date in the month
23
+ #@return [Month]
18
24
  def self.load(date_yaml)
19
25
  date = YAML.load(date_yaml)
20
26
  Month.containing(date)
21
27
  end
22
28
 
29
+ # Used by ActiveRecord::Base.serialize
30
+ #@param [Month] month
31
+ #@return [String] the YAML for the first date of the month
23
32
  def self.dump(month)
24
33
  YAML.dump(month.first_day)
25
34
  end
26
35
 
36
+ #@param [Integer] year the number of the year
37
+ #@param [Integer] month the number of the month
38
+ #@return [Month]
27
39
  def initialize(year, month)
28
40
  @year, @month = year, month
29
41
  end
30
42
 
43
+ #@return [Date] the first day of the month
31
44
  def first_day
32
45
  Date.new(year, month, 1)
33
46
  end
34
47
 
48
+ #@return [Date] the last day of the month
35
49
  def last_day
36
50
  first_day.end_of_month
37
51
  end
38
52
 
53
+ #@return [Time] the very beginning of the month
39
54
  def first_moment
40
55
  first_day.beginning_of_day
41
56
  end
42
57
 
58
+ #@return [Time] the very end of the month
43
59
  def last_moment
44
60
  last_day.end_of_day
45
61
  end
46
62
 
63
+ #@return [Month] the month preceeding this one
47
64
  def previous
48
65
  self - 1.month
49
66
  end
50
67
 
68
+ #@return [Month] the month following this one
51
69
  def next
52
70
  self + 1.month
53
71
  end
54
72
 
73
+ #@return [Range<Date, Date>] the range of dates in this month
55
74
  def date_range
56
75
  Range.new(first_day, last_day)
57
76
  end
58
77
 
78
+ #@return [Range<Time, Time>] the range of time in this month
59
79
  def time_range
60
80
  Range.new(first_moment, last_moment)
61
81
  end
62
82
 
83
+ #@param [Date, Time, #to_date] datish
84
+ #@return [Boolean] true if the month contains the date, false otherwise
63
85
  def contains?(datish)
64
86
  date = datish.to_date
65
87
  year == date.year && month == date.month
66
88
  end
67
89
 
90
+ # Adds the duration to the month
91
+ #@param [ActiveSupport::Duration] duration
92
+ #@return [Month]
68
93
  def +(duration)
69
94
  Month.containing(first_day + duration)
70
95
  end
71
96
 
97
+ # Subtracts the duration from the month
98
+ #@param [ActiveSupport::Duration] duration
99
+ #@return [Month]
72
100
  def -(duration)
73
101
  Month.containing(first_day - duration)
74
102
  end
75
103
 
104
+ #@!visibility private
76
105
  def <=>(other)
77
106
  if year == other.year
78
107
  month <=> other.month
@@ -81,10 +110,12 @@ module Monthify
81
110
  end
82
111
  end
83
112
 
113
+ #@!visibility private
84
114
  def hash
85
115
  [self.class, year, month].hash
86
116
  end
87
117
 
118
+ #@!visibility private
88
119
  def to_s
89
120
  "%d/%02d" % [year, month]
90
121
  end
@@ -92,13 +123,17 @@ module Monthify
92
123
  end
93
124
 
94
125
  module ::Kernel
95
- def Month(convertee)
96
- if convertee.is_a?(Month)
97
- convertee
98
- elsif convertee.respond_to?(:to_date)
99
- Month.containing(convertee.to_date)
126
+ # Globally accessible method to convert an argument into a Month.
127
+ # If the argument cannot be converted, it raises an ArgumentError
128
+ #@param [Month, #to_date] object_to_convert the object to convert to a Month
129
+ #@return [Month] the given Month or the Month containing the given date
130
+ def Month(object_to_convert)
131
+ if object_to_convert.is_a?(Month)
132
+ object_to_convert
133
+ elsif object_to_convert.respond_to?(:to_date)
134
+ Month.containing(object_to_convert.to_date)
100
135
  else
101
- raise ArgumentError, "Don't know how to convert #{convertee.inspect} to Month"
136
+ raise ArgumentError, "Don't know how to convert #{object_to_convert.inspect} to Month"
102
137
  end
103
138
  end
104
139
  end
@@ -1,3 +1,3 @@
1
1
  module Monthify
2
- VERSION = "0.0.1"
2
+ VERSION = "0.0.2"
3
3
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: monthify
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.1
4
+ version: 0.0.2
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2012-10-24 00:00:00.000000000 Z
12
+ date: 2012-10-25 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: activesupport
@@ -78,3 +78,4 @@ test_files:
78
78
  - spec/lib/monthify/core_ext/object_spec.rb
79
79
  - spec/lib/monthify/month_spec.rb
80
80
  - spec/spec_helper.rb
81
+ has_rdoc: