DatePeriodParser
Parse a date-period string like 2015-Q1 and returns the start and end DateTime.
Useful for reporting/pagination/search to filter records for a given time period.
It is not a natural language date parser like the chronic gem. But intends to parse common formats like ISO_8601.
# Example useage in a rails controller action
# GET /posts?period=2015-08
def index
date_range = DatePeriodParser.range(params["period"], default: "today")
@posts = Posts.where(created_at: date_range)
endExamples periods:
- years
YYYY - months
YYYY-MM - dates
YYYY-MM-DD - beginning of year/month to now
ytd,mtd - shorcuts
today,yesterdayandyday,current-month,previous-month,current-year,previous-year
Tested with all common Rubies, 1.9.3 .. 2.2, JRuby (1.9 mode). For details check .travis.yml
Examples
# year
DatePeriodParse.parse("2014")
#=> [<#DateTime 2014-01-01T00:00:00.000Z>, <#DateTime 2014-12-31T23:59:59.999Z>]
# months
DatePeriodParse.parse("2014-02")
#=> [<#DateTime 2014-02-01T00:00:00.000Z>, <#DateTime 2014-02-28T23:59:59.999Z>]
# day
DatePeriodParse.parse("2014-12-31")
#=> [<#DateTime 2014-12-31T00:00:00.000Z>, <#DateTime 2014-12-31T23:59:59.999Z>]
DatePeriodParse.parse("today")
#=> [<#DateTime 2015-08-31T00:00:00.000Z>, <#DateTime 2014-08-31T23:59:59.999Z>]
# timezone offsets
DatePeriodParse.parse("2014-12-31", offset: "+0700")
#=> [<#DateTime 2014-12-31T00:00:00.000+0700>, <#DateTime 2014-12-31T23:59:59.999+0700>]Installation
Add this line to your application's Gemfile:
gem 'date_period_parser'And then execute:
$ bundle
Or install it yourself as:
$ gem install date_period_parser
Recognized patterns
Values below for today: 2015-07-14 15:33
| Pattern | From | Until |
|---|---|---|
| 2015 | 2015-01-01 00:00 | 2015-12-31 23:59 |
| ytd | 2015-01-01 00:00 | 2015-07-14 15:33 |
| current-year | 2015-01-01 00:00 | 2015-07-31 23:59 |
| previous-year | 2014-01-01 00:00 | 2014-12-31 23:59 |
| 2015-07 | 2015-07-01 00:00 | 2015-07-31 23:59 |
| mtd | 2015-07-01 00:00 | 2015-07-14 15:33 |
| current-month | 2015-07-01 00:00 | 2015-07-31 23:59 |
| previous-month | 2015-06-01 00:00 | 2015-06-30 23:59 |
| 2015-12-31 | 2015-12-31 00:00 | 2015-12-31 23:59 |
| today | 2015-07-14 00:00 | 2015-07-14 23:59 |
| yesterday | 2015-07-13 00:00 | 2015-07-13 23:59 |
Difference between ytd and current-year (mtd and current-month respectively) is that ytd will return DateTime.now vs. current-month spans from first to last day of the month.
DatePeriodParser.parse
from,until = DatePeriodParser.parse("2014")
from # => #<DateTime 2014-01-01T00:00:00.000+0000")
until # => #<DateTime 2014-12-31T23:59:59.999+0000")
# 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")
# invalid periods
DatePeriodParser.parse("123213")
# => nil
# so you can do:
from,until = DatePeriodParser.parse("123213")
from ||= DateTime.yesterday
until ||= DateTime.now
# parse! raises ArgumentError for invalid periods
from,until = DatePeriodParser.parse!("123213")
#=> ArgumentError
# use :default option when period is optional
DatePeriodParser.parse(nil, default: "2014")
DatePeriodParser.parse("", default: "2014")DatePeriodParser.range
Works the same as DatePeriodParser.parse but returns a range.
rng = DatePeriodParser.range("2014")
rng.member? DateTime.new(2014,8,6)
# invalid periods return nil
rng = DatePeriodParser.range("dsf89sfd")
# => nil
# range! raises ArgumentError for invalid periods
rng = DatePeriodParser.range!("dsf89sfd")
#=> ArgumentErrorDevelopment
After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/hasclss/date_period_parser.
License
The gem is available as open source under the terms of the MIT License.