date_period_parser 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 133a42526128ad51856ce395e6c78d80b9bf055e
-  data.tar.gz: 275d7a0d7a3c2aa139b531258dba1381236e776e
+  metadata.gz: 90516f6773fd43e04a5134ea3c2d067d885ea5f8
+  data.tar.gz: 4038d871c3a4339bb709ef6e7010a4947ad5b2a5
 SHA512:
-  metadata.gz: 588749532d5a8686966fc13e4571ab2813b744c63955ffbfd70d63a39a2c6a2a65f7c6b99ba2c52b12143b83ed4788c610ba72f72bff938723052f2344b03fca
-  data.tar.gz: 77f86b17364e4d176d7d505b64ab7d4ec5157c3a3c49d2b91cfd00d2315b56358d8d260830f71e762518bc55eb4d962dfe3945bb817c4241e846ae9f73310ca9
+  metadata.gz: a4e833f6ad144dcf5c2883feb4f4f5d0fc31a245b1dce0b39fc22ff4310cb4f9d2f9405043a0bf0c404d50437a051bb00e974bdceb6b3c1e4d5ec79015e79c3a
+  data.tar.gz: c28fefc56507da2baa84c8dd79dece8e8cb0a5e3b09e6558724894d4d59946c5e07f0116d095b71dcdf5e9138242febbe116d048e9e2218ff5bc74120da77ec0

data/README.md

@@ -2,9 +2,9 @@
 
 # DatePeriodParser
 
-Parse a date-like string and returns it's start and end DateTime.
+Parse a date-period string like 2015-Q1 and returns the start and end DateTime.
 
-This can be used to pass date-periods for URL parameters or query strings, e.g. filtering records in a given period.
+Useful for reports to filterin records for a given time period.
 
 ```ruby
 # Example useage in a rails controller
@@ -12,10 +12,7 @@ This can be used to pass date-periods for URL parameters or query strings, e.g.
 class PostsController
   # GET /posts?period=2015-08
   def index
-    date_range = DatePeriodParser.range(params["period"])
-    # with user specific timezones
-    # date_range = DatePeriodParser.range(params["period"], offset: current_user.timezone)
-    date_range ||= DatePeriodParser.range("current-month") # default
+    date_range = DatePeriodParser.range(params["period"], default: "this-month")
     @posts = Posts.where(created_at: date_range)
   end
 end
@@ -115,8 +112,12 @@ from  ||= DateTime.yesterday
 until ||= DateTime.now
 
 # parse! raises ArgumentError for invalid periods
-from,until = DatePeriodParser.parse("123213")
+from,until = DatePeriodParser.parse!("123213")
 #=> ArgumentError
+
+# use :default option when period is optional
+DatePeriodParser.parse(nil, default: "2014")
+DatePeriodParser.parse("", default: "2014")
 ```
 
 ### DatePeriodParser.range
@@ -132,7 +133,7 @@ rng = DatePeriodParser.range("dsf89sfd")
 # => nil
 
 # range! raises ArgumentError for invalid periods
-rng = DatePeriodParser.range("dsf89sfd")
+rng = DatePeriodParser.range!("dsf89sfd")
 #=> ArgumentError
 ```
 

data/lib/date_period_parser.rb

@@ -5,76 +5,144 @@ require 'date'
 module DatePeriodParser
   DEFAULT_OFFSET = "+00:00".freeze
 
-  # ## Useage
+  # Returns array of start and end DateTime of given period string.
   #
-  #     from,until = DatePeriodParser.parse("2014")
-  #     from # => #<DateTime 2014-01-01T00:00:00.000+0000")
-  #     until   # => #<DateTime 2014-12-31T23:59:59.999+0000")
+  # @example Basic useage
+  #     DatePeriodParser.parse("2014")
+  #     # => [
+  #     #   #<DateTime 2014-01-01T00:00:00.000+0000">,
+  #     #   #<DateTime 2014-12-31T23:59:59.999+0000">
+  #     # ]
   #
-  #     # offsets:
+  # @example with timezone offsets:
   #     from,until = DatePeriodParser.parse("2014", offset: "+0700")
-  #     from # => #<DateTime 2014-01-01T00:00:00.000+0700")
-  #     until   # => #<DateTime 2014-12-31T23:59:59.999+0700")
+  #     from    # => #<DateTime 2014-01-01T00:00:00.000+0700">
+  #     until   # => #<DateTime 2014-12-31T23:59:59.999+0700">
   #
-  #     # invalid periods
+  # @example invalid periods
   #     DatePeriodParser.parse("123213") # => nil
   #     from,until = DatePeriodParser.parse("123213")
-  #     from # => nil
-  #     until # => nil
+  #     from    # => nil
+  #     until   # => nil
   #
+  # @param  [String] period date period string.
+  # @option options [String] :offset ("+0000") timezone offset, e.g. "+0700"
+  # @option options [String] :default (nil) use this default if `period` is nil
+  # @return [Array<DateTime, DateTime>] start and end DateTime
+  # @return [nil] if period string is invalid
   #
-  #
-  def parse(str, options = {})
-    parse!(str, options)
+  def parse(period, options = {})
+    parse!(period, options)
   rescue ArgumentError => e
     nil
   end
 
-  def parse!(str, options = {})
-    Base.new(str, options).parse
+  # Same as #parse but raises an ArgumentError if period string is invalid
+  #
+  # @example Basic useage
+  #     def my_method
+  #       from,until = DatePeriodParser.parse!("FOOBAR")
+  #     rescue ArgumentError => e
+  #        # do something
+  #     end
+  #
+  # @see #parse
+  # @param  [String] period date period string.
+  # @raise [ArgumentError] if period string is invalid
+  # @option options [String] :offset ("+0000") timezone offset, e.g. "+0700"
+  # @option options [String] :default (nil) use this default if `period` is nil
+  # @return [Array<DateTime, DateTime>] start and end DateTime
+  #
+  def parse!(period, options = {})
+    period = options[:default] if period.nil? || period.empty?
+    Base.new(period, options).parse
   end
 
-  def range(str, options = {})
-    range!(str, options)
+  # Same as #parse but returns a range instead
+  #
+  # @example Basic useage
+  #     rng = DatePeriodParser.range("2014")
+  #     rng.member? DateTime.new(2014,8,6)
+  #
+  # @see #parse
+  # @param  [String] period date period string.
+  # @raise [ArgumentError] if period string is invalid
+  # @option options [String] :offset ("+0000") timezone offset, e.g. "+0700"
+  # @option options [String] :default (nil) use this default if `period` is nil
+  # @return [Range<DateTime, DateTime>] start and end DateTime as range
+  #
+  def range(period, options = {})
+    range!(period, options)
   rescue ArgumentError => e
     nil
   end
 
-  def range!(str, options = {})
-    first,last = Base.new(str, offset).parse
+  # Same as #range but raises an ArgumentError if period string is invalid
+  #
+  # @example Basic useage
+  #     def my_method
+  #       rng = DatePeriodParser.range!("FOOBAR")
+  #     rescue ArgumentError => e
+  #        # do something
+  #     end
+  #
+  # @see #parse
+  # @param  [String] period date period string.
+  # @raise [ArgumentError] if period string is invalid
+  # @option options [String] :offset ("+0000") timezone offset, e.g. "+0700"
+  # @option options [String] :default (nil) use this default if `period` is nil
+  # @return [Range<DateTime, DateTime>] start and end DateTime as range
+  #
+  def range!(period, options = {})
+    period = options[:default] if period.nil? || period.empty?
+    first,last = Base.new(period, offset).parse
     first..last
   end
 
   module_function :parse, :parse!, :range, :range!
 
+  # @api private
   class Base
     attr_reader :value, :offset
 
     def initialize(value, options = nil)
       options ||= {} # in case someone sends Base.new("", nil)
-      @value    = value.freeze
+      @value    = value.to_s.freeze
       @offset = (options[:offset] || options['offset'] || DEFAULT_OFFSET).freeze
     end
 
     def parse
       case @value
-      when /\Atoday\Z/                then parse_date(Date.today)
-      when /\Ayesterday\Z/            then parse_date(Date.today - 1)
-      when /\Ayday\Z/                 then parse_date(Date.today - 1)
-      when /\Acurrent-month\Z/        then parse_month(Date.today)
-      when /\Aprevious-month\Z/       then parse_month(Date.today << 1)
-      when /\Acurrent-year\Z/         then parse_year(Date.today)
-      when /\Aprevious-year\Z/        then parse_year(Date.today << 12)
-      when /\Amtd\Z/                  then mtd
-      when /\Aytd\Z/                  then ytd
-      when /\A\d\d\d\d\Z/             then parse_year
-      when /\A\d\d\d\d\-\d\d\Z/       then parse_month
-      when /\A\d\d\d\d\-\d\d\-\d\d\Z/ then parse_date
+      when /\Atoday\Z/i                then parse_date(Date.today)
+      when /\Ayesterday\Z/i            then parse_date(Date.today - 1)
+      when /\Ayday\Z/i                 then parse_date(Date.today - 1)
+      when /\Acurrent-month\Z/i        then parse_month(Date.today)
+      when /\Aprevious-month\Z/i       then parse_month(Date.today << 1)
+      when /\Acurrent-year\Z/i         then parse_year(Date.today)
+      when /\Aprevious-year\Z/i        then parse_year(Date.today << 12)
+      when /\Amtd\Z/i                  then mtd
+      when /\Aqtd\Z/i                  then quarter_of(Date.today.year, Date.today.month)
+      when /\Aytd\Z/i                  then ytd
+      when /\A\d\d\d\d\-Q\d\Z/i        then parse_quarter
+      when /\A\d\d\d\d\Z/i             then parse_year
+      when /\A\d\d\d\d\-\d\d\Z/i       then parse_month
+      when /\A\d\d\d\d\-\d\d\-\d\d\Z/i then parse_date
       else raise ArgumentError.new("invalid date period")
       end
     end
 
   protected
+    def quarter_of(year, month)
+      case month
+      when  1..3  then [start_of_date(Date.new(year,  1)), end_of_date(Date.new(year,  3, 31))]
+      when  4..6  then [start_of_date(Date.new(year,  4)), end_of_date(Date.new(year,  6, 30))]
+      when  7..9  then [start_of_date(Date.new(year,  7)), end_of_date(Date.new(year,  9, 30))]
+      when 10..12 then [start_of_date(Date.new(year, 10)), end_of_date(Date.new(year, 12, 31))]
+      else
+        raise ArgumentError.new("invalid date period")
+      end
+    end
+
     def now_with_offset
       d = DateTime.now
       DateTime.new(d.year, d.month, d.day, d.hour, d.minute, d.second, offset)
@@ -125,6 +193,12 @@ module DatePeriodParser
       ]
     end
 
+    def parse_quarter
+      year, quarter = @value.upcase.split("-Q").map(&:to_i)
+
+      quarter_of(year, (quarter - 1) * 3 + 1)
+    end
+
     def parse_year(date = nil)
       if date.nil?
         year = @value.to_i

data/lib/date_period_parser/version.rb

@@ -1,3 +1,3 @@
 module DatePeriodParser
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/spec/date_period_parser_spec.rb

@@ -8,6 +8,7 @@ describe DatePeriodParser do
   end
 
   it 'parse' do
+    assert parse(:today) != nil
     assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0000"),  parse("2014").first
     assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0000"),  parse("2014", nil).first
     assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0000"),  parse("2014", {}).first
@@ -17,6 +18,13 @@ describe DatePeriodParser do
     assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0700"),  parse("2014", {'offset' => "+0700"}).first
   end
 
+  it 'parse with :default' do
+    assert parse(:today) != nil
+    assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0000"),  parse(nil, default: "2014").first
+    assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0000"),  parse("", default: "2014").first
+    assert_equal nil,  parse("Invalid20", default: "2014")
+  end
+
   it '2014' do
     assert_equal DateTime.new(2014, 1, 1,  0,  0,  0.000, "+0000"),  parse("2014").first
     assert_equal DateTime.new(2014,12,31, 23, 59, 59.999, "+0000"),  parse("2014").last
@@ -58,7 +66,7 @@ describe DatePeriodParser do
   it 'today' do
     t = Date.today
     assert_equal DateTime.new(t.year, t.month, t.day, 0, 0, 0.000, "+0000"),  parse("today").first
-    assert_equal DateTime.new(t.year, t.month, t.day,23,59,59.999, "+0000"),  parse("today").last
+    assert_equal DateTime.new(t.year, t.month, t.day,23,59,59.999, "+0000"),  parse("today".upcase).last
   end
 
   # https://en.wikipedia.org/wiki/ISO_8601#Week_dates
@@ -66,25 +74,30 @@ describe DatePeriodParser do
   end
 
   it '2015-Q1' do
+    assert_equal DateTime.new(2015, 1, 1,  0,  0,  0.000, "+0000"),  parse("2015-q1").first
+    assert_equal DateTime.new(2015, 3,31, 23, 59, 59.999, "+0000"),  parse("2015-Q1").last
+
+    assert_equal DateTime.new(2015, 1, 1,  0,  0,  0.000, "-0300"),  parse("2015-Q1", offset: "-0300").first
+    assert_equal DateTime.new(2015, 3,31, 23, 59, 59.999, "-0300"),  parse("2015-Q1", offset: "-0300").last
   end
 
   it 'yesterday' do
     t = Date.today - 1
     assert_equal DateTime.new(t.year, t.month, t.day, 0, 0, 0.000, "+0000"),  parse("yesterday").first
-    assert_equal DateTime.new(t.year, t.month, t.day,23,59,59.999, "+0000"),  parse("yesterday").last
+    assert_equal DateTime.new(t.year, t.month, t.day,23,59,59.999, "+0000"),  parse("yesterday".upcase).last
   end
 
   it 'yday' do
     t = Date.today - 1
     assert_equal DateTime.new(t.year, t.month, t.day, 0, 0, 0.000, "+0000"),  parse("yday").first
-    assert_equal DateTime.new(t.year, t.month, t.day,23,59,59.999, "+0000"),  parse("yday").last
+    assert_equal DateTime.new(t.year, t.month, t.day,23,59,59.999, "+0000"),  parse("yday".upcase).last
   end
 
 
   it 'ytd' do
     t = DateTime.now
     assert_equal DateTime.new(t.year, 1, 1, 0, 0, 0.000, "+0000"),                        parse("ytd").first
-    assert_equal DateTime.new(t.year, t.month, t.day, t.hour,t.minute,t.second, "+0000"), parse("ytd").last
+    assert_equal DateTime.new(t.year, t.month, t.day, t.hour,t.minute,t.second, "+0000"), parse("ytd".upcase).last
 
     assert_equal DateTime.new(t.year, 1, 1, 0, 0, 0.000, "+0400"),                        parse("ytd", offset: "+0400").first
     assert_equal DateTime.new(t.year, t.month, t.day, t.hour,t.minute,t.second, "+0400"), parse("ytd", offset: "+0400").last
@@ -93,21 +106,66 @@ describe DatePeriodParser do
   it 'mtd' do
     t = DateTime.now
     assert_equal DateTime.new(t.year, t.month, 1, 0, 0, 0.000, "+0000"),                  parse("mtd").first
-    assert_equal DateTime.new(t.year, t.month, t.day, t.hour,t.minute,t.second, "+0000"), parse("mtd").last
+    assert_equal DateTime.new(t.year, t.month, t.day, t.hour,t.minute,t.second, "+0000"), parse("mtd".upcase).last
 
     assert_equal DateTime.new(t.year, t.month, 1, 0, 0, 0.000, "+0400"),                  parse("mtd", offset: "+0400").first
     assert_equal DateTime.new(t.year, t.month, t.day, t.hour,t.minute,t.second, "+0400"), parse("mtd", offset: "+0400").last
-    end
+  end
 
   it 'wtd' do
   end
 
+  it "quarter_of" do
+    # private methods
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 1)
+    assert_equal DateTime.new(2015, 1, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 3,31, 23,59, 59.999, "+0000"), to
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 2)
+    assert_equal DateTime.new(2015, 1, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 3,31, 23,59, 59.999, "+0000"), to
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 3)
+    assert_equal DateTime.new(2015, 1, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 3,31, 23,59, 59.999, "+0000"), to
+
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 4)
+    assert_equal DateTime.new(2015, 4, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 6,30, 23,59, 59.999, "+0000"), to
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 6)
+    assert_equal DateTime.new(2015, 4, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 6,30, 23,59, 59.999, "+0000"), to
+
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 7)
+    assert_equal DateTime.new(2015, 7, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 9,30, 23,59, 59.999, "+0000"), to
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 9)
+    assert_equal DateTime.new(2015, 7, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 9,30, 23,59, 59.999, "+0000"), to
+
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 10)
+    assert_equal DateTime.new(2015, 10, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 12,31, 23,59, 59.999, "+0000"), to
+    from,to = DatePeriodParser::Base.new("foobar").send(:quarter_of, 2015, 12)
+    assert_equal DateTime.new(2015, 10, 1,  0, 0,  0,     "+0000"), from
+    assert_equal DateTime.new(2015, 12,31, 23,59, 59.999, "+0000"), to
+  end
+
+  it 'qtd' do
+    t = Date.today
+    from,to = DatePeriodParser::Base.new("foo").send(:quarter_of, t.year, t.month)
+
+    assert_equal DateTime.new(from.year, from.month, 1, 0, 0, 0.000, "+0000"),                  parse("qtd").first
+    assert_equal DateTime.new(to.year, to.month, to.day, to.hour,to.minute,to.second+0.999, "+0000"), parse("qtd".upcase).last
+
+    assert_equal DateTime.new(from.year, from.month, 1, 0, 0, 0.000, "+0400"),                        parse("qtd", offset: "+0400").first
+    assert_equal DateTime.new(to.year, to.month, to.day, to.hour,to.minute,to.second+0.999, "+0400"), parse("qtd", offset: "+0400").last
+  end
+
   it 'current-month' do
     t = Date.today
     last = t >> 1 # same day, next month
     last = Date.new(last.year, last.month, 1) - 1
     assert_equal DateTime.new(t.year, t.month, 1, 0, 0, 0.000, "+0000"),        parse("current-month").first
-    assert_equal DateTime.new(t.year, t.month, last.day,23,59,59.999, "+0000"), parse("current-month").last
+    assert_equal DateTime.new(t.year, t.month, last.day,23,59,59.999, "+0000"), parse("current-month".upcase).last
   end
 
   it 'previous-month' do
@@ -115,19 +173,19 @@ describe DatePeriodParser do
     last = t >> 1 # same day, next month
     last = Date.new(last.year, last.month, 1) - 1
     assert_equal DateTime.new(t.year, t.month, 1, 0, 0, 0.000, "+0000"),        parse("previous-month").first
-    assert_equal DateTime.new(t.year, t.month, last.day,23,59,59.999, "+0000"), parse("previous-month").last
+    assert_equal DateTime.new(t.year, t.month, last.day,23,59,59.999, "+0000"), parse("previous-month".upcase).last
   end
 
   it 'current-year' do
     t = Date.today
     assert_equal DateTime.new(t.year,  1,  1, 0, 0, 0.000, "+0000"), parse("current-year").first
-    assert_equal DateTime.new(t.year, 12, 31,23,59,59.999, "+0000"), parse("current-year").last
+    assert_equal DateTime.new(t.year, 12, 31,23,59,59.999, "+0000"), parse("current-year".upcase).last
   end
 
   it 'previous-year' do
     t = Date.today << 12
     assert_equal DateTime.new(t.year,  1,  1, 0, 0, 0.000, "+0000"), parse("previous-year").first
-    assert_equal DateTime.new(t.year, 12, 31,23,59,59.999, "+0000"), parse("previous-year").last
+    assert_equal DateTime.new(t.year, 12, 31,23,59,59.999, "+0000"), parse("previous-year".upcase).last
   end
 
   describe "with offsets" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: date_period_parser
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - hasclass
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-08-19 00:00:00.000000000 Z
+date: 2015-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,3 +98,4 @@ specification_version: 4
 summary: Parse a date-like string and returns it's start and end DateTime.
 test_files:
 - spec/date_period_parser_spec.rb
+has_rdoc: