active_period 6.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 244cb233b1cdd1aeac905c1c7467cdb90a9bd4179ed28d2c14928ebd5cd95308
+  data.tar.gz: 98776fbef793f99dc2f0ac63bb8dbd380fb709878f9eb2985cb393e008622f99
+SHA512:
+  metadata.gz: 27251125b3cb392249e94eeeec0feb6faf4836dff714a1bd9996ffa032ea782b264798b07fea01ccf019fd8d2f2583a049fda7b0438156a297a4f20e0484fdf8
+  data.tar.gz: eae48296375f9d0323c4e2e2b5356a135dd9287dbe345f315526363b9e5c578ae858239434c1729fb0b9b01c6c80a5de01cbf259eb83cbe7637814d5dfb453bb

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in period.gemspec
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,36 @@
+PATH
+  remote: .
+  specs:
+    active_period (6.0.0)
+      activesupport (~> 6)
+      i18n (~> 1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.1.3.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    concurrent-ruby (1.1.8)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    minitest (5.14.4)
+    rake (10.5.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  ruby
+  x86_64-darwin-19
+
+DEPENDENCIES
+  active_period!
+  bundler (~> 2.0)
+  rake (~> 10.0)
+
+BUNDLED WITH
+   2.2.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 billau_l
+
+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,342 @@
+# ActivePeriod 
+[![Gem Version](https://badge.fury.io/rb/active_period.svg)](https://badge.fury.io/rb/active_period) 
+[![Code Climate](https://codeclimate.com/github/billaul/period.svg)](https://codeclimate.com/github/billaul/period) 
+[![Inline docs](http://inch-ci.org/github/billaul/period.svg)](http://inch-ci.org/github/billaul/period) 
+[![RubyGems](http://img.shields.io/gem/dt/active_period.svg?style=flat)](http://rubygems.org/gems/active_period)
+
+ActivePeriod aims to simplify Time-range manipulation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_period'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_period
+
+## Usage
+
+**ActivePeriod** was designed to simplify time-range manipulation, specialy with rails (>= 5) and user input   
+
+**Warning** :
+- A time-range take place between two **date** and it's different from an abstract duration of time
+- **ActivePeriod** is limited at full day of time and will always round the starting and ending to the beginning and the ending of the day
+
+
+## Quick view (TL;DR)
+``` ruby
+require 'active_period'
+
+# Get all user created today
+User.where(created_at: Period.today)
+
+# Get how many days there is from the Voyager 2 launch
+('20/07/1977'..Time.now).to_period.days.count
+
+# Are we in 2021 ?
+Time.now.in? Period.year('01/01/2021')
+
+# Boundless period are also supported
+Period.new('24/04/1990'..).days.each # => Enumerable
+Period.new(..Time.now).months.reverse_each # => Enumerable
+
+# Write a date for me (I18n supported)
+Period.new('20/01/2017'...'20/01/2021').to_s
+=> "From the 20 January 2017 to the 20 January 2021 excluded"
+```
+
+## Detailed view
+
+There's two way to create and manipulate a period of time `FreePeriod` and `StandardPeriod`
+
+### FreePeriod of time
+
+You can declare **FreePeriod** as simply as :
+
+```ruby
+# With Date objects
+Period.new(3.month.ago..Date.today)
+
+# or with Strings
+Period.new('01/01/2000'...'01/02/2000')
+
+# or with a mix
+Period.new('01/01/2000'..1.week.ago)
+
+# with one bound only
+Period.new('01/01/2000'..)
+
+# or in a rails Controller with params
+Period.new(params[:start_date]..params[:end_date])
+
+# or from a range
+('01/01/2000'...'01/02/2000').to_period
+```
+
+**Note** : `to_period` will always return a **FreePeriod**
+
+**FreePeriod** can be manipulated with `+` and `-`          
+Doing so will move the start **and** the end of the period   
+```ruby
+Period.new('01/01/2000'..'05/01/2000') + 3.day
+# is equal to
+Period.new('04/01/2000'..'08/01/2000')
+```
+
+### StandardPeriod of time
+
+Using **StandardPeriod** you are limited to strictly bordered periods of time      
+These periods are `day`, `week`, `month`, `quarter` and `year`
+
+```ruby
+# To get the week, 42th day ago
+Period.week(42.day.ago)
+
+# To get the first month of 2020
+Period.month('01/01/2020')
+
+# or if you like it verbious
+ActivePeriod::Month.new('01/01/2020')
+
+# or if you need the current week
+Period.week(Time.now)
+```
+
+**Note** : If you ask for a `month`, `quarter` of `year`, the day part of your param doesn't matter `01/01/2020` give the same result as `14/01/2020` or `29/01/2020`
+
+**StandardPeriod** can be manipulated with `+` and `-` and will always return a **StandardPeriod** of the same type           
+```ruby
+# Subtraction are made from the start of the period
+Period.month('10/02/2000') - 1.day
+# Return the previous month
+
+# Addition are made from the end
+Period.month('10/02/2000') + 1.day
+# Return the next month
+
+Period.week('10/02/2000') + 67.day
+# Return a week
+```
+**StandardPeriod** also respond to `.next` and `.prev`
+```ruby
+Period.month('01/01/2000').next.next.next
+# Return the month of April 2020
+```
+
+You can quickly access convenient periods of time with `.(last|this|next)_(day|week|month|quarter|year)` and `.yesterday` `.today` `.tomorrow`
+
+```ruby
+Period.this_week
+# Same as Period.week(Time.now) but shorter
+
+Period.next_month
+# Return the next month
+
+Period.last_year
+# Return the last year
+
+Period.today
+# No comment
+```
+
+## HasMany
+
+**FreePeriod** and some **StandardPeriod** respond to `.days`, `.weeks`, `.months`, `.quarters` and `.years`    
+
+| HasMany -> [\<StandardPeriod>] | .days | .weeks | .months | .quarters | .years |
+|-------------------------------|:----:|:-----:|:------:|:--------:|:-----:|
+| FreePeriod                    |   X  |   X   |    X   |     X    |   X   |
+| StandardPeriod::Day           |      |       |        |          |       |
+| StandardPeriod::Week          |   X  |       |        |          |       |
+| StandardPeriod::Month         |   X  |   X   |        |          |       |
+| StandardPeriod::Quarter       |   X  |   X   |    X   |          |       |
+| StandardPeriod::Year          |   X  |   X   |    X   |     X    |       |
+
+Called from a **FreePeriod** all overlapping **StandardPeriod** are return     
+Called from a **StandardPeriod** only strictly included **StandardPeriod** are return     
+These methods return an **ActivePeriod::Collection** implementing **Enumerable**
+
+#### Example
+```ruby
+# The FreePeriod from 01/01/2021 to 01/02/2021 has 5 weeks
+Period.new('01/01/2021'...'01/02/2021').weeks.count # 5
+
+# The StandardPeriod::Month for 01/01/2021 has 4 weeks
+Period.month('01/01/2021').weeks.count # 4
+
+# How many day in the current quarter
+Period.this_quarter.days.count
+
+# Get all the quarters overlapping a Period of time
+Period.new(Time.now..2.month.from_now).quarters.to_a
+```
+
+## BelongsTo
+
+**StandardPeriod** respond to `.day`, `.week`, `.month`, `.quarter` and `.year`        
+These methods return a **StandardPeriod** who include the current period    
+**FreePeriod** does not respond to these methods
+
+| BelongTo -> StandardPeriod | .day | .week | .month | .quarter | .year |
+|----------------------------|:---:|:----:|:-----:|:-------:|:----:|
+| FreePeriod                 |     |      |       |         |      |
+| StandardPeriod::Day        |     |   X  |   X   |    X    |   X  |
+| StandardPeriod::Week       |     |      |   X   |    X    |   X  |
+| StandardPeriod::Month      |     |      |       |    X    |   X  |
+| StandardPeriod::Quarter    |     |      |       |         |   X  |
+| StandardPeriod::Year       |     |      |       |         |      |
+
+#### Example with BelongTo and HasMany
+
+```ruby
+# Get the third day, of the last week, of the second month, of the current year
+Period.this_year.months.second.weeks.last.days.third
+```
+
+## Boundless Period
+
+Boundless period are fully supported and work as you expect them to do    
+The values `nil`, `''`, `Date::Infinity`, `Float::INFINITY` and `-Float::INFINITY` are supported as start and end
+You can iterate on the `days`, `weeks`, `months`, `quarters` and `years` of an Endless period
+```ruby
+('01/01/2021'..nil).days.each { ... }
+('01/01/2021'..'').days.each { ... }
+('01/01/2021'..).days.each { ... }
+```
+You can reverse iterate on the `days`, `weeks`, `months`, `quarters` and `years` of an Beginless period
+```ruby
+(nil..'01/01/2021').days.reverse_each { ... }
+(''..'01/01/2021').days.reverse_each { ... }
+(..'01/01/2021').days.reverse_each { ... }
+```
+
+You can create an infinite period of time     
+Obviously it's not iterable
+```ruby
+Period.new(nil..nil).to_s
+=> "Limitless time range"
+```
+
+You can specifically forbid boundless period with `allow_endless`, `allow_beginless` or with `Period.bounded`
+```ruby
+Period.new('01/01/2020'..'', allow_endless: false)
+Period.bounded('01/01/2020'..)
+=> ArgumentError (The end date is invalid)
+
+Period.new(..'01/01/2020', allow_beginless: false)
+Period.bounded(..'01/01/2020')
+=> ArgumentError (The start date is invalid)
+```
+
+## ActiveRecord
+
+As **Period** inherit from **Range**, you can natively use them in **ActiveRecord** query
+
+```ruby
+# Get all book published this year
+Book.where(published_at: Period.this_year)
+
+# Get all users created after 01/01/2020
+User.where(created_at: ('01/01/2020'..).to_period)
+```
+
+## Rails Controller
+
+In a Controller, use the error handling to validate the date for you
+
+```ruby
+class BookController < ApplicationController
+  def between
+    begin
+      # Retrieve books from the DB
+      @books = Book.where(published: Period.bounded(params[:from]..params[:to]))
+    rescue ArgumentError => e
+      # Period will handle mis-formatted date and incoherent period
+      # I18n is supported for errors messages
+      flash[:alert] = e.message
+    end
+  end
+end
+```
+
+## I18n and to_s
+
+I18n is supported for `en` and `fr`   
+
+```ruby
+Period.new('01/01/2000'...'01/02/2001').to_s
+=> "From the 01 January 2000 to the 31 January 2001 included"
+
+I18n.locale = :fr
+Period.new('01/01/2000'...'01/02/2001').to_s
+=> "Du 01 janvier 2000 au 31 janvier 2001 inclus"
+```
+Errors are also supported
+```ruby
+Period.new 'Foo'..'Bar'
+=> ArgumentError (The start date is invalid)
+
+Period.new '01/02/3030'..'Bar'
+Period.bounded '01/02/3030'..
+=> ArgumentError (The end date is invalid)
+
+Period.new '01/02/3030'..'01/01/2020'
+=> ArgumentError (The start date is greater than the end date)
+```
+
+See `locales/en.yml` to implement your language support
+
+If you need to change the format for a single call
+
+```ruby
+  period.to_s(format: 'Your Format')
+  # or
+  period.strftime('Your Format')
+```
+For a FreePeriod or if you need to print the start and the end of your period differently, use `.i18n`
+```ruby
+  period.i18n do |from, to, excluded_end|
+    "You have from #{from.strftime(...)} until #{to.strftime(...)} to deliver the money !"
+  end
+```
+
+## The tricky case of Weeks
+
+Weeks are implemented following the [ISO 8601](https://en.wikipedia.org/wiki/ISO_week_date)      
+So `Period.this_month.weeks.first` doesn't necessarily include the first days of the month
+Also a **StandardPeriod** and a **FreePeriod** covering the same range of time, may not includes the same `Weeks`
+
+## TimeZone
+
+Time zone are supported
+If you change the global `Time.zone` of your app
+If your Period [begin in a time zone and end in another](https://en.wikipedia.org/wiki/Daylight_saving_time), you have nothing to do
+
+## Planned updates
+
+- [ ] ActiveRecord Serializer (maybe)
+- [ ] Holidays support (gem Holidays) -> COMING SOON
+
+## Bug reports
+
+If you discover any bugs, feel free to create an [issue on GitHub](https://github.com/billaul/active_period/issues)        
+Please add as much information as possible to help us in fixing the potential bug     
+We also encourage you to help even more by forking and sending us a pull request
+
+No issues will be addressed outside GitHub
+
+## Maintainer
+
+* Myself (https://github.com/billaul)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+task default: :spec
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc 'Run tests'
+task default: :test

data/active_period.gemspec

@@ -0,0 +1,44 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_period/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'active_period'
+  spec.version       = ActivePeriod::VERSION
+  spec.authors       = ['billau_l']
+
+  spec.summary       = 'Manage time ranges without brain damage.'
+  # spec.description   = "Period.new('01/01/2020'..Time.now)"
+  spec.homepage      = "https://github.com/billaul/period"
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+    spec.metadata["bug_tracker_uri"]   = spec.homepage + '/issues'
+    spec.metadata["homepage_uri"]      = spec.homepage
+    spec.metadata["documentation_uri"] = spec.homepage
+    spec.metadata["source_code_uri"]   = spec.homepage
+    # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = %w[lib config]
+
+  spec.required_ruby_version = '>= 2.7'
+  spec.add_runtime_dependency 'activesupport', '~> 5'
+  spec.add_runtime_dependency 'i18n', '~> 1'
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end