merch_calendar 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 94429998c8a78882cafaba7e479b5a8af2e75b08
+  data.tar.gz: d1ece80b55e67aa6dd9236888095770f13a7aedb
+SHA512:
+  metadata.gz: 505cbc69d351c12bb201d6d720c2504542a2d4f3998983bf006580a89fb9c72b4cd63e5b18ae301d69c7cb17a38938b8e9ccd819bf1ca9e15f49915eb05cc458
+  data.tar.gz: caad2d4f70d937baaf692eca58f46829644c318a9436b9bb14029f62182c520f3ad2a8c009b261fedec3861122221c5da46108d215abc7c2de10060d091951f1

data/.gitignore

@@ -0,0 +1,3 @@
+coverage/
+doc
+.yardoc/

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,71 @@
+PATH
+  remote: .
+  specs:
+    merch_calendar (0.0.1)
+
+GEM
+  remote: https://www.rubygems.org/
+  specs:
+    coderay (1.1.0)
+    coveralls (0.8.1)
+      json (~> 1.8)
+      rest-client (>= 1.6.8, < 2)
+      simplecov (~> 0.10.0)
+      term-ansicolor (~> 1.3)
+      thor (~> 0.19.1)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    domain_name (0.5.24)
+      unf (>= 0.0.5, < 1.0.0)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
+    json (1.8.2)
+    method_source (0.8.2)
+    mime-types (2.5)
+    netrc (0.10.3)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.4.2)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.2)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    slop (3.6.0)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
+    tins (1.5.1)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls
+  merch_calendar!
+  pry
+  rake
+  rspec (>= 3.0.0)
+  simplecov

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2015 Stitch Fix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# Merch Calendar
+
+[![Build Status](https://travis-ci.org/stitchfix/merch_calendar.svg)](https://travis-ci.org/stitchfix/merch_calendar)
+[![Code Climate](https://codeclimate.com/github/stitchfix/merch_calendar/badges/gpa.svg)](https://codeclimate.com/github/stitchfix/merch_calendar)
+[![Coverage Status](https://coveralls.io/repos/stitchfix/merch_calendar/badge.svg)](https://coveralls.io/r/stitchfix/merch_calendar)
+
+This gem allows for finding retail/merchandising weeks for a given date, along with manipulating the retail calendar. This gem is used at [StitchFix](http://www.stitchfix.com/).
+
+## Installation
+
+```bash
+$ gem install merch_calendar
+```
+
+Add the following line to your `Gemfile`:
+```ruby
+gem "merch_calendar"
+```
+
+
+## Configuration
+```ruby
+# NOTE: Configuration will be added soon, but is currently NOT available.
+MerchCalendar.configure do |config|
+  # The month that Q1 begins. The default is 8 (August)
+  config.quarter_start_month = 8
+end
+```
+
+## Usage
+
+For converting a date into a `MerchWeek` object.
+
+```ruby
+merch_week = MerchCalendar::MerchWeek.from_date("2014-01-01")
+puts merch_week.year # 2013 (the merch year associated with this date)
+puts merch_week.month # 12 (the julian month that the date falls in)
+puts merch_week.week # 5 (the week number within the month)
+puts merch_week.year_week # 48 (the week number within the year)
+puts merch_week.quarter # 2
+
+puts merch_week.start_of_week # <Date: 2013-12-29>
+puts merch_week.end_of_week # <Date>
+
+puts merch_week.start_of_month # <Date>
+puts merch_week.end_of_month # <Date>
+
+puts merch_week.start_of_quarter # <Date>
+puts merch_week.end_of_quarter # <Date>
+
+puts merch_week.start_of_year # <Date>
+puts merch_week.end_of_year # <Date>
+
+# Formatting
+puts merch_week.to_s # "Dec W5"
+puts merch_week.to_s(:short) # "Dec W5"
+puts merch_week.to_s(:long) # "2013:48 Dec W5"
+puts merch_week.to_s(:elasticsearch) # "2013-12w05"
+```
+
+This can also be used on the `MerchCalendar` module. All `start_` and `end_` methods can be called, along with a few additional ones.
+
+```ruby
+# All examples below return a Date object for the start of May within the 2014 merch year
+MerchCalendar.start_of_month(2014, 5)
+MerchCalendar.start_of_month(2014, month: 5)
+MerchCalendar.start_of_month(2014, julian_month: 5)
+
+# This is the same as May, because "Merch" months are shifted by 1.
+# i.e. month 1 is actually February
+# You probably will never use this, but it is available.
+MerchCalendar.start_of_month(2014, merch_month: 4)
+```
+
+Other useful methods:
+
+```ruby
+# 52 or 53 (depending on leap year)
+MerchCalendar.weeks_in_year(2015)
+
+# returns an array of MerchWeek objects for each week within the provided month
+MerchCalendar.weeks_for_month(2014, 1)
+```
+
+## Documentation
+You can view the documentation for this gem on [RubyDoc.info](http://www.rubydoc.info/github/stitchfix/merch_calendar/master).
+
+
+## Roadmap
+* Support for 4-4-5 calendars
+
+## License
+MerchCalendar is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rubygems/package_task'
+require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new
+
+task default: :spec

data/lib/merch_calendar/configurable.rb

@@ -0,0 +1,28 @@
+module MerchCalendar
+  class << self
+
+    attr_writer :configuration
+
+    # Returns the global configuration object
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Used in initializers to set the global configuration
+    #
+    # @return [void]
+    def configure
+      yield(configuration)
+    end
+
+    # Resets the configuration to default values
+    #
+    # @return [void]
+    def reset_config!
+      @configuration = Configuration.new
+    end
+
+  end
+end

data/lib/merch_calendar/configuration.rb

@@ -0,0 +1,13 @@
+module MerchCalendar
+  # @note WARNING: THIS IS NOT BEING USED YET
+  class Configuration
+
+    # The JULIAN month of the quarter start
+    attr_accessor :quarter_start_month
+
+    def initialize
+      @quarter_start_month = 8
+    end
+
+  end
+end

data/lib/merch_calendar/date_calculator.rb

@@ -0,0 +1,103 @@
+module MerchCalendar
+
+  # @api private
+  class DateCalculator
+
+    def end_of_year(year)
+      year_end = Date.new (year + 1), 1, -1
+      wday = (year_end.wday + 1) % 7
+
+      if wday > 3
+        year_end += 7 - wday
+      elsif wday > 0
+        year_end -= wday
+      end
+      year_end
+    end
+
+    # The day after last years' end date
+    def start_of_year(year)
+      end_of_year(year - 1) + 1
+    end
+
+    # The starting date of a given month
+    # THIS IS THE MERCH MONTH
+    # 1 = feb
+    # 
+    def start_of_month(year, merch_month)
+      # 91 = number of days in a single 4-5-4 set 
+      start = start_of_year(year) + ((merch_month - 1) / 3).to_i * 91
+
+      case merch_month
+      when 2,5,8,11
+        # 28 = 4 weeks
+        start = start + 28
+      when 3,6,9,12
+        # The 5 week months
+        # 63 = 4 weeks + 5 weeks
+        start = start + 63
+      end
+      
+      start
+    end
+
+    def end_of_month(year, merch_month)
+      if merch_month == 12
+        end_of_year(year)
+      else
+        start_of_month(year, merch_month + 1) - 1
+      end
+    end
+
+    # Return the starting date for a particular quarter
+    def start_of_quarter(year, quarter)
+      case quarter
+      when 1
+        start_of_month(year, 7)
+      when 2
+        start_of_month(year, 10)
+      when 3
+        start_of_month(year, 1)
+      when 4
+        start_of_month(year, 4)
+      end
+    end
+
+    # Return the ending date for a particular quarter
+    def end_of_quarter(year, quarter)
+      case quarter
+      when 1
+        end_of_month(year, 9)
+      when 2
+        end_of_month(year, 12)
+      when 3
+        end_of_month(year, 3)
+      when 4
+        end_of_month(year, 6)
+      end
+    end
+
+    # Return the number of weeks in a particular year
+    def weeks_in_year(year)
+      ((start_of_year(year + 1) - start_of_year(year)) / 7).to_i
+    end
+
+    def merch_to_julian(merch_month)
+      if merch_month == 12
+        1
+      else
+        merch_month + 1
+      end
+    end
+
+    def julian_to_merch(julian_month)
+      if julian_month == 1
+        12
+      else
+        julian_month - 1
+      end
+    end
+
+
+  end
+end

data/lib/merch_calendar/merch_week.rb

@@ -0,0 +1,224 @@
+module MerchCalendar
+
+  # Represents the Merch Week for a specified date.
+  class MerchWeek
+
+    MONTHS = %w(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec).freeze
+
+    # The Julian date that is being represented
+    #
+    # @!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
+      end
+    end
+
+
+
+    # Pass in a date, make sure it is a valid date object
+    # @private
+    def initialize(date, options = {})
+      @date = date
+
+      # 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]
+      @end_of_year = options[:end_of_year]
+
+      @start_of_week = options[:start_of_week]
+      @end_of_week = options[:end_of_week]
+      @week = options[:week]
+
+      @start_of_month = options[:start_of_month]
+      @end_of_month = options[:end_of_month]
+    end
+
+    # What week it is within the year from 1-53
+    #
+    # @return [Fixnum] The week number of the year, from 1-53
+    def year_week
+      @year_week ||= (((date-start_of_year)+1)/7.0).ceil
+    end
+
+    # This returns the "merch month" number for a date
+    # Merch months are shifted by one. Month 1 is Feb
+    #
+    # @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_month ||= (1..12).detect do |num|
+        date_calc.end_of_month(start_of_year.year, num) >= date && date >= date_calc.start_of_month(start_of_year.year, num)
+      end
+    end
+
+    # The merch year
+    #
+    # @return [Fixnum]
+    def year
+      start_of_year.year
+    end
+
+    # The julian month that this merch week falls in
+    #
+    # @return [Fixnum]
+    def month
+      @month ||= date_calc.merch_to_julian(merch_month)
+    end
+
+    # The specific quarter this week falls in
+    #
+    # @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
+    end
+
+    # Returns the date of the start 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
+    #
+    # @return [Date]
+    def end_of_week
+      @end_of_week ||= (start_of_week + 6)
+    end
+
+    # the number of the week within the given month
+    # will be between 1 and 5
+    #
+    # @return [Fixnum]
+    def week
+      @week ||= (((date-start_of_month)+1)/7.0).ceil
+    end
+
+    # The date of the start of the corresponding merch year
+    #
+    # @return [Date]
+    def start_of_year
+      @start_of_year ||= year_start_date
+    end
+
+    # The end date of the corresponding merch year
+    #
+    # @return [Date]
+    def end_of_year
+      @end_of_year ||= date_calc.end_of_year(year)
+    end
+
+    # The start date of the merch month
+    #
+    # @return [Date]
+    def start_of_month
+      @start_of_month ||= date_calc.start_of_month(year, merch_month)
+    end
+
+    # The end date of the merch month
+    #
+    # @return [Date]
+    def end_of_month
+      @end_of_month ||= date_calc.end_of_month(year, merch_month)
+    end
+
+    # The merch season this date falls under.
+    # Returns a string of +Fall/Winter+ or +Spring/Summer+
+    #
+    # @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
+    end
+
+    # Outputs a text representation of this merch week
+    #
+    # Format keys:
+    # * +:short+ (default) "Dec W5"
+    # * +:long+ "2012:48 Dec W5"
+    # * +:elasticsearch+ (default) "2012-12w05"
+    #
+    # @param format [Symbol] the format identifier to return. Default is +:short+
+    #
+    # @return [Date]
+    def to_s(format = :short)
+      case format
+      when :elasticsearch
+        sprintf("%04d-%02dw%02d", year, month, week)
+      when :long
+        "#{year}:#{year_week} #{self.to_s(:short)}"
+      else
+        "#{MONTHS[month - 1]} W#{week}"
+      end
+    end
+
+    private
+
+    def year_start_date
+      start_date = date_calc.start_of_year(date.year)
+      if start_date > date
+        start_date = date_calc.start_of_year(date.year - 1)
+      end
+      start_date
+    end
+
+    def date_calc
+      @date_calc ||= DateCalculator.new
+    end
+
+  end
+end