merch_calendar 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c82e19a6628132edf5ef227e08d270fc8e1aa3ef
-  data.tar.gz: 6bcc92b82007ee4cf137435092ac7df7f6f24a33
+  metadata.gz: 13a41aecf0152a0c3bffeed5ecf51f15dd5d6927
+  data.tar.gz: 482637d57739642817b9c8729f6598fdd4ba4ff7
 SHA512:
-  metadata.gz: a532b4acdd1a97639b1894b53181279f750531fd5ac99b2d5f95d40f9cc5330a26b17f8eb85e5304f8a9477596378c22db4355c0f6f39b6766c93730c5e945fd
-  data.tar.gz: 6360b4c0c3c20d6565dae5fc83f2e089c50f6b0fa159a9af99211363316bd3be8bebe5075c5a0bb79253d22a85cd63e53f6dd9e9979c22d6c495569429e8967a
+  metadata.gz: cee1f7ae6cf8817c0616eb46eb572f3a39cf6deb087ed6515335ad693030ae5106353915199be23b471d53e494a7f190ba7ccf021523c66674fd96e52ac71085
+  data.tar.gz: c49c4924295a06b57a71c164a2f6c57a6b433ef25b0eb3359e42da3cec27f8b3f25affc94009c57337cf4d872747deddff78585a4a95c65e57b3093aa7bd6e03

data/Gemfile

@@ -1,3 +1,3 @@
 source 'https://www.rubygems.org'
 
-gemspec
+gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    merch_calendar (0.1.0)
+    merch_calendar (0.3.0)
 
 GEM
   remote: https://www.rubygems.org/
@@ -58,4 +58,4 @@ DEPENDENCIES
   simplecov
 
 BUNDLED WITH
-   1.15.1
+   1.15.3

data/README.md

@@ -24,13 +24,13 @@ gem "merch_calendar"
 For converting a date into a `MerchWeek` object.
 
 ```ruby
-merch_week = MerchCalendar::MerchWeek.from_date("2014-01-01")
+merch_week = MerchCalendar::MerchWeek.from_date("2014-01-01", calendar: MerchCalendar::RetailCalendar.new)
 
 merch_week.year                 # 2013 (the merch year associated with this date)
 merch_week.month                # 12 (the julian month that the date falls in)
 merch_week.week                 # 5 (the week number within the month)
-merch_week.year_week            # 48 (the week number within the year)
-merch_week.quarter              # 2
+merch_week.year_week            # 48 (the week number within the retail calendar year)
+merch_week.quarter              # 4
 
 merch_week.start_of_week        # <Date: 2013-12-29>
 merch_week.end_of_week          # <Date: 2014-01-04>
@@ -41,6 +41,9 @@ merch_week.end_of_month         # <Date: 2014-01-04>
 merch_week.start_of_year        # <Date: 2013-02-03>
 merch_week.end_of_year          # <Date: 2014-02-01>
 
+merch_week.calendar             # <MerchCalendar::RetailCalendar> (the calendar we're using)
+                                # if you don't initialize a calendar, it defaults to RetailCalendar
+
 # Formatting
 merch_week.to_s                 # "Dec W5"
 merch_week.to_s(:short)         # "Dec W5"
@@ -51,7 +54,7 @@ merch_week.to_s(:elasticsearch) # "2013-12w05"
 
 ### Merch retail calendar
 
-Merch calendars have their first month in February, and the last (12th) month is in January of the
+Retail calendars have their first month in February, and the last (12th) month is in January of the
 following year.
 
 ```ruby
@@ -102,18 +105,17 @@ retail_calendar.end_of_week(2017, 4, 1)
 #=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>
 ```
 
-### Offset fiscal year calendars
-Some companies, one of which being Stitch Fix, operate on a fiscal year calendar that is offset from
-the traditional retail calendar.  The `MerchCalendar::FiscalYearCalendar` class allows you to easily
-offset the start of year to match your fiscal calendar.
+### Stitch Fix Fiscal Year Calendars
+Some companies, one of which being Stitch Fix, operate on a fiscal year calendar that instead starts in August 
+rather than in February in a the traditional retail calendar.  The `MerchCalendar::StitchFixFiscalYearCalendar` class 
+allows you to easily translate Gregorian dates to a Stitch Fix Fiscal Year date.
 
 ```ruby
-fiscal_calendar = MerchCalendar::FiscalYearCalendar.new
+fiscal_calendar = MerchCalendar::StitchFixFiscalYearCalendar.new
 
-# 52 or 53 (depending on leap year)
-fiscal_calendar.weeks_in_year(2017)
-# => 52
 fiscal_calendar.weeks_in_year(2018)
+# => 52
+fiscal_calendar.weeks_in_year(2019)
 # => 53
 
 # get the start date of a given merch week
@@ -125,6 +127,39 @@ fiscal_calendar.end_of_week(2017, 4, 1)
 #=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>
 ```
 
+#### Stitch Fix Fiscal Year Calendar in Relation to MerchWeek object
+You can set MerchWeek object respond to the Stitch Fix Fiscal Calendar, by passing in `StitchFixFiscalYearCalendar.new` in the calendar parameter:
+
+```ruby
+merch_week = MerchCalendar::MerchWeek.from_date("2018-07-02", calendar: MerchCalendar::StitchFixFiscalYearCalendar.new)
+
+merch_week.year                 # 2018 (the merch year associated with this date)
+merch_week.month                # 7 (the julian month that the date falls in)
+merch_week.merch_month          # 12 (this fiscal month the date falls in)
+merch_week.week                 # 1 (the week number within the month)
+merch_week.year_week            # 49 (the week number within the retail calendar year)
+merch_week.quarter              # 4
+
+merch_week.start_of_week        # <Date: 2018-07-01>
+merch_week.end_of_week          # <Date: 2018-07-07>
+
+merch_week.start_of_month       # <Date: 2018-07-01>
+merch_week.end_of_month         # <Date: 2018-07-28>
+
+merch_week.start_of_year        # <Date: 2017-07-30>
+merch_week.end_of_year          # <Date: 2018-07-28>
+
+merch_week.calendar             # <MerchCalendar::StitchFixFiscalYearCalendar> (the calendar
+                                # we're using)
+                                # if you don't initialize a calendar, it defaults to RetailCalendar
+
+# Formatting
+merch_week.to_s                 # "Jul W1"
+merch_week.to_s(:short)         # "Jul W1"
+merch_week.to_s(:long)          # "2018:49 Jul W1"
+merch_week.to_s(:elasticsearch) # "2018-07w01"
+```
+
 ## Documentation
 You can view the documentation for this gem on [RubyDoc.info](http://www.rubydoc.info/github/stitchfix/merch_calendar/master).
 

data/lib/merch_calendar/merch_week.rb

@@ -1,6 +1,6 @@
 module MerchCalendar
 
-  # Represents the Merch Week for a specified date.
+  # Represents the Merch Week for a specified date and calendar
   class MerchWeek
 
     MONTHS = %w(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec).freeze
@@ -10,56 +10,68 @@ module MerchCalendar
     # @!attribute [r] date
     #   @return [Date] the date for this merch week
     attr_reader :date
-
-    class << self
-
-      # Locates the +MerchWeek+ for a given Julian date.
-      #
-      # @overload from_date(String)
-      #   @param [String] julian_date a julian date in the format of +YYYY-MM-DD+
-      # @overload from_date(Date)
-      #   @param [Date] julian_date a +Date+ object
-      #
-      # @return [MerchWeek]
-      def from_date(julian_date)
-        MerchWeek.new Date.parse("#{julian_date}")
-      end
-
-      # Returns an array of merch weeks for a month, or a specific week.
-      #
-      # @overload find(year, julian_month)
-      #   Returns an array of +MerchWeek+s for a given month
-      #   @param year [Fixnum] the merch year to locate
-      #   @param julian_month [Fixnum] the month to find merch months for
-      #   @return [Array<MerchWeek>]
-      # @overload find(year, julian_month, week_number)
-      #   @param year [Fixnum] the merch year to locate
-      #   @param julian_month [Fixnum] the month to find merch months for
-      #   @param week_number [Fixnum] the specific week number.
-      #   @return [MerchWeek] the specific merch week
-      def find(year, julian_month, week_number=nil)
-        if week_number.nil?
-          MerchCalendar.weeks_for_month(year, julian_month)
-        else
-          MerchCalendar.weeks_for_month(year, julian_month)[week_number-1]
-        end
-      end
-
-      # Returns the +MerchWeek+ for today's date
-      #
-      # @return [MerchWeek]
-      def today
-        MerchWeek.from_date Date.today
+    
+    # The Merch Calendar that is being represented, either Fiscal or Retail
+    #
+    # @!attribute [r] calendar
+    #   @return [Class] the calendar that determines the merch week
+    attr_reader :calendar
+
+    # Locates the +MerchWeek+ for a given Julian date.
+    #
+    # @overload from_date(String)
+    #   @param julian_date [String] a julian date in the format of +YYYY-MM-DD+
+    #   @param options [Hash] opts the options to set your calendar, if none it will default to RetailCalendar
+    #   # @option opts [Class] :calendar The Calendar Class
+    # @overload from_date(Date)
+    #   @param julian_date [Date] julian_date a +Date+ object
+    #   @param options [Hash] opts the options to set your calendar, if none it will default to RetailCalendar
+    #   # @option opts [Class] :calendar The Calendar Class
+    # @return [MerchWeek]
+    def self.from_date(julian_date, options = {})
+      MerchWeek.new(Date.parse("#{julian_date}"), options)
+    end
+
+    # Returns an array of merch weeks for a month, or a specific week.
+    #
+    # @overload find(year, julian_month, week_number=nil, options)
+    #   Returns an array of +MerchWeek+s for a given month
+    #   @param year [Fixnum] the merch year to locate
+    #   @param julian_month [Fixnum] the month to find merch months for
+    #   @param week_number [Nil] set week_number to nil
+    #   @param options [Hash] options to set your calendar, if none it will default to RetailCalendar
+    #   @return [Array<MerchWeek>]
+    # @overload find(year, julian_month, week_number)
+    #   @param year [Fixnum] the merch year to locate
+    #   @param julian_month [Fixnum] the month to find merch months for
+    #   @param week_number [Fixnum] the specific week number.
+    #   @param options [Hash] options to set your calendar, if none it will default to RetailCalendar
+    #   @return [MerchWeek] the specific merch week based on the week number
+    def self.find(year, julian_month, week_number=nil, options={})
+      calendar = options.fetch(:calendar, RetailCalendar.new)
+      if week_number.nil?
+        calendar.weeks_for_month(year, julian_month)
+      else
+        calendar.weeks_for_month(year, julian_month)[week_number-1]
       end
     end
 
-
+    # Returns the +MerchWeek+ for today's date
+    #
+    #   @param options [Hash] opts the options to set your calendar, if none it will default to RetailCalendar
+    #   # @option opts [Class] :calendar The Calendar Class
+    # @return [MerchWeek]
+    def self.today(options={})
+      MerchWeek.from_date(Date.today, options)
+    end
 
     # Pass in a date, make sure it is a valid date object
     # @private
     def initialize(date, options = {})
       @date = date
-
+      
+      #defaults to Retail Calendar if no other calendar is defined
+      @calendar = options.fetch(:calendar, RetailCalendar.new)
       # Placeholders. These should be populated by functions if nil
       # week_start: nil, week_end: nil, week_number: nil
       @start_of_year = options[:start_of_year]
@@ -81,62 +93,55 @@ module MerchCalendar
     end
 
     # This returns the "merch month" number for a date
-    # Merch months are shifted by one. Month 1 is Feb
+    # Month 1 is Feb for the retail calendar
+    # Month 1 is August for the fiscal calendar
     #
     # @return [Fixnum]
     def merch_month
       # TODO: This is very inefficient, but less complex than strategic guessing
       # maybe switch to a binary search or something
+      merch_year = calendar.merch_year_from_date(date)
       @merch_month ||= (1..12).detect do |num|
-        retail_calendar.end_of_month(start_of_year.year, num) >= date && date >= retail_calendar.start_of_month(start_of_year.year, num)
+        calendar.end_of_month(merch_year, num) >= date && date >= calendar.start_of_month(merch_year, num)
       end
     end
 
-    # The merch year
+    # Returns the Merch year depending whether it is from the Retail or Fiscal calendar
     #
     # @return [Fixnum]
     def year
-      start_of_year.year
+      @year ||= calendar.merch_year_from_date(date)
     end
 
-    # The julian month that this merch week falls in
+    # Returns julian month where the merch week falls
     #
     # @return [Fixnum]
     def month
-      @month ||= MerchCalendar.merch_to_julian(merch_month)
+      @month ||= calendar.merch_to_julian(merch_month)
     end
 
-    # The specific quarter this week falls in
+    # Returns the quarter that this merch week falls
     #
     # @return [Fixnum]
     def quarter
-      case merch_month
-      when 7,8,9
-        return 1
-      when 10,11,12
-        return 2
-      when 1,2,3
-        return 3
-      else
-        return 4
-      end
+      @quarter ||= calendar.quarter(merch_month)
     end
 
-    # Returns the date of the start of this week
+    # Returns the start date of this week
     #
     # @return [Date]
     def start_of_week
       @start_of_week ||= (start_of_month + (7 * (week - 1)))
     end
 
-    # Returns the date of the end of this week
+    # Returns the end date of this week
     #
     # @return [Date]
     def end_of_week
       @end_of_week ||= (start_of_week + 6)
     end
 
-    # the number of the week within the given month
+    # The number of the week within the given merch month
     # will be between 1 and 5
     #
     # @return [Fixnum]
@@ -144,32 +149,32 @@ module MerchCalendar
       @week ||= (((date-start_of_month)+1)/7.0).ceil
     end
 
-    # The date of the start of the corresponding merch year
+    # The start date of the corresponding merch year
     #
     # @return [Date]
     def start_of_year
-      @start_of_year ||= year_start_date
+      @start_of_year ||= calendar.start_of_year(year)
     end
 
     # The end date of the corresponding merch year
     #
     # @return [Date]
     def end_of_year
-      @end_of_year ||= retail_calendar.end_of_year(year)
+      @end_of_year ||= calendar.end_of_year(year)
     end
 
     # The start date of the merch month
     #
     # @return [Date]
     def start_of_month
-      @start_of_month ||= retail_calendar.start_of_month(year, merch_month)
+      @start_of_month ||= calendar.start_of_month(year, merch_month)
     end
 
     # The end date of the merch month
     #
     # @return [Date]
     def end_of_month
-      @end_of_month ||= retail_calendar.end_of_month(year, merch_month)
+      @end_of_month ||= calendar.end_of_month(year, merch_month)
     end
 
     # The merch season this date falls under.
@@ -177,12 +182,7 @@ module MerchCalendar
     #
     # @return [String]
     def season
-      case merch_month
-      when 1,2,3,4,5,6
-        "Spring/Summer"
-      when 7,8,9,10,11,12
-        "Fall/Winter"
-      end
+      @season ||= calendar.season(merch_month)
     end
 
     # Outputs a text representation of this merch week
@@ -193,7 +193,6 @@ module MerchCalendar
     # * +:elasticsearch+ (default) "2012-12w05"
     #
     # @param format [Symbol] the format identifier to return. Default is +:short+
-    #
     # @return [Date]
     def to_s(format = :short)
       case format
@@ -205,20 +204,5 @@ module MerchCalendar
         "#{MONTHS[month - 1]} W#{week}"
       end
     end
-
-    private
-
-    def year_start_date
-      start_date = retail_calendar.start_of_year(date.year)
-      if start_date > date
-        start_date = retail_calendar.start_of_year(date.year - 1)
-      end
-      start_date
-    end
-
-    def retail_calendar
-      @retail_calendar ||= RetailCalendar.new
-    end
-
   end
 end