week_sauce 0.0.1 → 0.0.2

data/README.md

@@ -1,89 +1,138 @@
-# WeekSauce
-
-WeekSauce is a simple class that functions as a days-of-the-week bitmask.
-Useful for things that repeat weekly, and/or can occur or one or more days
-of the week.
-
-Extracted from a Rails app, it's intended to be used an ActiveRecord
-attribute serializer, but it should work fine outside of Rails.
-
-## Basic usage
-
-    week = WeekSauce.new(16) # set a specific bitmask
-    week.blank?     #=> false
-    week.one?       #=> true
-    week.thursday?  #=> true
-    
-    week = WeekSauce.new     # defaults to a zero-bitmask
-    week.blank? #=> true
-    
-    # Mark off the weekend
-    week.set(:saturday, :sunday)
-    
-    from = Time.parse("2013-04-01") # A Monday
-    week.next_date(from)            #=> "2013-04-06" (a Saturday)
-    
-    week.dates_in(from..from + 1.week) => ["2013-04-06", "2013-04-07"]
-
-## Rails usage
-
-    class Workout < ActiveRecord::Base
-      serialize :days, WeekSauce
-    end
-    
-    workout = Workout.find_by_kind("Weights")
-    workout.days.to_s #=> "Monday, Wednesday"
-    workout.days.set!(:tuesday, :thursday) # sets only those days
-    workout.save
+# WeekSauce [![Build Status](https://travis-ci.org/Flambino/week_sauce.png?branch=master)](https://travis-ci.org/Flambino/week_sauce) [![Gem Version](https://badge.fury.io/rb/week_sauce.png)](http://badge.fury.io/rb/week_sauce) [![Code Climate](https://codeclimate.com/github/Flambino/week_sauce.png)](https://codeclimate.com/github/Flambino/week_sauce)
+
+WeekSauce is a simple class that functions as a days-of-the-week bitmask. Useful for things that repeat weekly, and/or can occur on one or more days of the week.
+
+It was extracted from a Rails app, and is primarily intended to used as an ActiveRecord attribute serializer, but it should work fine outside of Rails too.
+
+## Installation
+
+It's a gem, so:
+
+    gem install week_sauce
+
+or, if you're using Bundler, put this in your Gemfile:
+
+    gem 'week_sauce'
+
+## The Basics
+
+``` ruby
+week = WeekSauce.new(16) # init with bitmask (optional)
+week.blank?     #=> false
+week.one?       #=> true
+week.thursday?  #=> true
+
+week = WeekSauce.new     # defaults to a zero-bitmask
+week.blank? #=> true
+
+# Mark the weekend
+week.set(:saturday, :sunday)
+
+from = Time.parse("2013-04-01") # A Monday
+week.next_date(from)            #=> Sat, 06 Apr 2013
+
+week.dates_in(from..from + 1.week) => [Sat, 06 Apr 2013 , Sun, 07 Apr 2013]
+```
+
+## Usage with ActiveRecord
+
+``` ruby
+class Workout < ActiveRecord::Base
+  serialize :days, WeekSauce
+end
+
+workout = Workout.find_by_kind("Weights")
+workout.days.inspect #=> "20: Tuesday, Thursday"
+
+workout.days.set!(:tuesday, :thursday) # sets only those days
+workout.save
+```
+
+The underlying `days` database column can be either a string or integer type.
 
 ## API
 
-Individual days can be set and read using Fixnums, symbols or Date/Time
-objects. Additionally, there are named methods for getting and setting
-each of the week's days:
-
-    # These are all equivalent
-    week.monday   = true
-    week[:monday] = true
-    week[1]       = true
-    
-    time = Time.parse("2013-04-01") # A Monday
-    week[time] = true
-    week[time.to_date] = true
-    
-    # And these are equivalent too
-    week.monday   #=> true
-    week.monday?  #=> true
-    week[:monday] #=> true
-    week[1]       #=> true
-    week[time]    #=> true
+Individual days can be set and read using Fixnums, strings, symbols or Date/Time objects. Additionally, there are named methods for getting and setting each of the week's days:
+
+``` ruby
+time = Time.parse("2013-04-01") # A Monday
+
+# These are all equivalent
+week.monday        = true
+week[:monday]      = true
+week["monday"]     = true # case-insensitive
+week[1]            = true
+week["1"]          = true
+week[time]         = true
+week[time.to_date] = true
+
+# And these are equivalent too
+week.monday        #=> true
+week.monday?       #=> true
+week[:monday]      #=> true
+week["monday"]     #=> true (again, case-insensitive)
+week[1]            #=> true
+week["1"]          #=> true
+week[time]         #=> true
+week[time.to_date] #=> true
+```
 
 _Note that similar to `Date#wday`, Sunday is `0`, Monday is `1` and so forth._
 
-There are also a few value-checking methods:
+Several days can be set or unset using the so-named methods:
 
-    week.blank? # true if no days are set
-    week.one?   # true if exactly 1 day is set
-    week.any?   # true if at least 1 day is set
-    week.many?  # true if at least 2 days are set
-    week.all?   # true if all days are set
+``` ruby
+# arguments can also be Fixnums or Date/Time objects
+week.set(:monday, :wednesday)    # set those days to true
+week.unset(:monday, :wednesday)  # set those days to false
+```
 
-Several days can be set or unset using the so-named methods:
+These also have "exclusive" versions:
 
-    # arguments can also be Fixnums or Date/Time objects
-    week.set(:monday, :wednesday)    # set those days to true
-    week.unset(:monday, :wednesday)  # set those days to false
+``` ruby
+week.set!(:monday, :wednesday)   # sets *only* those days to true, all others to false
+week.unset!(:monday, :wednesday) # sets *only* those days to false, all others to true
+```
+
+There are also a few value-checking methods:
 
-These also have "exclusive" versions
+``` ruby
+week.blank?  # true if no days are set
+week.one?    # true if exactly 1 day is set
+week.any?    # true if at least 1 day is set
+week.many?   # true if at least 2 days are set
+week.all?    # true if all days are set
 
-    week.set!(:monday, :wednesday)   # sets *only* those days to true, all others to false
-    week.unset!(:monday, :wednesday) # set *only* those days to false, all others to true
+# The == comparison operator works with other WeekSauce objects and Fixnums
+week == other_week #=> true if the bitmask values match
+week == 123        #=> true if the bitmask value == 123
+```
 
-Lastly, dates matching the week's bitmask can be calculated
+And a couple of methods to find dates matching the week's bitmask:
 
-    week.dates_in(from..to)   # find matching dates in a range
-    
-    week.next_date            # finds next matching date from today
-    week.next_date(some_date) # finds next matching date from (and including) some_date
+``` ruby
+week.dates_in(from..to)   # find matching dates in a range of dates
+
+week.next_date            # finds next matching date from today
+week.next_date(some_date) # finds next matching date from (and including) some_date
+```
+
+In this example, `some_date` may be either a `Date` or a `Time` object. If it's the latter, it'll be converted using `#to_date`.
 
 If ActiveSupport's time zone support is available, `next_date` with no argument will default to the time zone-aware `Date.current` instead of `Date.today`.
+
+Lastly, a few utility methods:
+
+``` ruby
+week.to_i    #=> the raw integer bitmask
+week.to_a    #=> array of the selected days' names, e.g. [:monday, :thursday]
+week.to_hash #=> hash with day names as keys, and the day's boolean state as value
+week.count   #=> number of days set (0..7)
+week.inspect #=> string describing the bitmask values and days, e.g. "3: Sunday, Monday"
+```
+
+## Odds and ends
+
+The gem was extracted from a Rails 3.2 app, and requires Ruby 1.9.2 or higher. The requirement is undoubtedly overkill, but the specs currently use the 1.9+ hash syntax. It could be converted very easily though (feel free!).
+
+The code has good test coverage (using RSpec), and is tested against [a few 1.9 and 2.0 rubies using TravisCI](https://travis-ci.org/Flambino/week_sauce).

data/lib/week_sauce.rb

@@ -1,40 +1,44 @@
 require 'date'
-
-# WeekSauce is a simple class that functions as a days-of-the-week bitmask.
-# Useful for things that repeat weekly, and/or can occur or one or more days
-# of the week.
 # 
-# Extracted from a Rails app, it's intended to be used an ActiveRecord
-# attribute serializer, but it should work fine outside of Rails.
+# {<img src="https://travis-ci.org/Flambino/week_sauce.png?branch=master" alt="Build Status" />}[https://travis-ci.org/Flambino/week_sauce]
+# {<img src="https://badge.fury.io/rb/week_sauce.png" alt="Gem Version" />}[http://badge.fury.io/rb/week_sauce]
+# {<img src="https://codeclimate.com/github/Flambino/week_sauce.png" />}[https://codeclimate.com/github/Flambino/week_sauce]
 # 
-# == Basic usage
+# WeekSauce is a simple class that functions as a days-of-the-week bitmask. Useful for things that repeat weekly, and/or can occur on one or more days of the week.
 # 
-#     week = WeekSauce.new(16) # set a specific bitmask
-#     week.blank?     #=> false
-#     week.one?       #=> true
-#     week.thursday?  #=> true
-#     
-#     week = WeekSauce.new     # defaults to a zero-bitmask
-#     week.blank? #=> true
-#     
-#     # Mark off the weekend
-#     week.set(:saturday, :sunday)
-#     
-#     from = Time.parse("2013-04-01") # A Monday
-#     week.next_date(from)            #=> "2013-04-06" (a Saturday)
-#     
-#     week.dates_in(from..from + 1.week) => ["2013-04-06", "2013-04-07"]
+# It was extracted from a Rails app, and is primarily intended to used as an ActiveRecord attribute serializer, but it should work fine outside of Rails too.
 # 
-# == Rails usage
+# == The Basics
 # 
-#     class Workout < ActiveRecord::Base
-#       serialize :days, WeekSauce
-#     end
-#     
-#     workout = Workout.find_by_kind("Weights")
-#     workout.days.to_s #=> "Monday, Wednesday"
-#     workout.days.set!(:tuesday, :thursday) # sets only those days
-#     workout.save
+#   week = WeekSauce.new(16) # init with bitmask (optional)
+#   week.blank?     #=> false
+#   week.one?       #=> true
+#   week.thursday?  #=> true
+#   
+#   week = WeekSauce.new     # defaults to a zero-bitmask
+#   week.blank? #=> true
+#   
+#   # Mark the weekend
+#   week.set(:saturday, :sunday)
+#   
+#   from = Time.parse("2013-04-01") # A Monday
+#   week.next_date(from)            #=> Sat, 06 Apr 2013
+#   
+#   week.dates_in(from..from + 1.week) => [Sat, 06 Apr 2013 , Sun, 07 Apr 2013]
+# 
+# == Usage with ActiveRecord
+# 
+#   class Workout < ActiveRecord::Base
+#     serialize :days, WeekSauce
+#   end
+#   
+#   workout = Workout.find_by_kind("Weights")
+#   workout.days.inspect #=> "20: Tuesday, Thursday"
+#   
+#   workout.days.set!(:tuesday, :thursday) # sets only those days
+#   workout.save
+# 
+# The underlying `days` database column can be either a string or integer type.
 # 
 class WeekSauce
   MAX_VALUE = 2**7 - 1
@@ -54,7 +58,7 @@ class WeekSauce
     
     # ActiveRecord attribute serialization support
     # 
-    # Dump a WeekSauce instance to a stringified instance bitmask
+    # Dump a WeekSauce instance to a stringified bitmask value
     def dump(instance)
       if instance.is_a?(self)
         instance.to_i.to_s
@@ -73,7 +77,7 @@ class WeekSauce
     @value = [[0, value.to_i].max, MAX_VALUE].min
   end
   
-  # Compare this instance against another instance, or a Fixnum
+  # Compare this instance against another instance or a Fixnum
   def ==(arg)
     case arg
     when self.class, Fixnum
@@ -110,6 +114,7 @@ class WeekSauce
     any? && !one?
   end
   
+  # Create the day=, day, and day? methods
   DAY_BITS.each do |day, bit|
     define_method(day) do
       get_bit bit
@@ -121,12 +126,15 @@ class WeekSauce
     end
   end
   
-  # Returns +true+ if the given weekday is set, +false+ if it isn't,
+  # Returns +true+ if the given day is set, +false+ if it isn't,
   # and +nil+ if the argument was invalid.
   # 
-  # The +wday+ argument can be a Fixnum from 0 (Sunday) to 6 (Saturday),
-  # a symbol specifying the day's name (e.g. +:tuesday+, +:friday+), or
-  # a Date or Time instance
+  # The +wday+ argument can be
+  # - a Fixnum from 0 (Sunday) to 6 (Saturday),
+  # - a day-name symbol, e.g. +:tuesday+, +:friday+,
+  # - a day-name string (case-insensitive), e.g. <tt>"Monday"</tt>, <tt>"sunday"</tt>
+  # - a Time object, or
+  # - a Date object
   def [](wday)
     get_bit coerce_to_bit(wday)
   end
@@ -145,7 +153,7 @@ class WeekSauce
     end
   end
   
-  # Exclusive version of #set - clears the week, and sets only
+  # Exclusive version of #set. Clears the week, and sets only
   # the days passed. Returns +self+
   def set!(*days)
     blank!
@@ -161,7 +169,7 @@ class WeekSauce
     end
   end
   
-  # Exclusive version of #unset - sets all days to true and
+  # Exclusive version of #unset. Sets all days to true and
   # then unsets days passed. Returns +self+
   def unset!(*days)
     all!
@@ -191,6 +199,17 @@ class WeekSauce
     DAY_NAMES.select { |day| self[day] }
   end
   
+  # Returns a hash where the keys are the week's 7 days
+  # as symbols, and the values are booleans
+  def to_hash
+    Hash[ DAY_NAMES.map { |day| [day, self[day]] } ]
+  end
+  
+  # Returns the number of "set" days
+  def count
+    to_a.count
+  end
+  
   # Returns a string with the bitmask value and a list of
   # "set" days, or a simple message if all/no days are set
   def inspect
@@ -204,18 +223,15 @@ class WeekSauce
     end
   end
   
-  # Returns a hash where the keys are the week's 7 days
-  # as symbols, and the values are booleans
-  def to_hash
-    Hash[ DAY_NAMES.map { |day| [day, self[day]] } ]
-  end
-  
   # Return the next date matching the bitmask, or +nil+ if the
   # week is blank.
   # 
   # If no +from_date+ argument is given, it'll default to
   # <tt>Date.current</tt> if ActiveSupport is available,
-  # or <tt>Date.today</tt> otherwise.
+  # otherwise it'll use <tt>Date.today</tt>.
+  # 
+  # If +from_date+ argument can be a +Date+ or a +Time+ object
+  # (the latter will be converted using +#to_date+)
   # 
   # If +from_date+ is given, #next_date will return the first
   # matching date from - and including - +from_date+
@@ -267,10 +283,13 @@ class WeekSauce
       case wday
       when Symbol
         DAY_BITS[wday]
-      when Fixnum
+      when Fixnum, /\A[0-6]\Z/
+        wday = wday.to_i
         (0..6).include?(wday) ? 2**wday : nil
       when Date, Time
         2**wday.wday
+      when /\A(sun|mon|tues|wednes|thurs|fri|satur)day\Z/i
+        DAY_BITS[wday.downcase.to_sym]
       end
     end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: week_sauce
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-03 00:00:00.000000000 Z
+date: 2013-06-04 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
@@ -64,7 +80,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: