smart-period 1.0.1 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5df770ae3301222917ed286b21cd001dffedfabcbcd957b7645231a85dac6ea9
-  data.tar.gz: bd565e152c142c751229ff4e3fd8f17f0085f6445722902fb9ba5fe75af4ddf4
+  metadata.gz: e2f52d692e80ad1fd610219f147275d392a3a74d127ccc52ce29fea1a6809f56
+  data.tar.gz: f43df7bfa7bff5caff9229979fb7dc02e91c3ebab263362118e23f37ddb473f9
 SHA512:
-  metadata.gz: eef66c5e59a8054c20647d74cd7beb3749f6683fe359dd7f7effc31c2d659c624a3277b5378039089fd494175515d64cd77eb8a29e8a3ee3917bda65ec708b31
-  data.tar.gz: 737039391b6228fccabf86725e55e75aa0381044ffbd7d7887d9b480d264ccbaa3b4fcead214efbdbfaa83a24c334818c365cd276140302c2a14f0a11a15de5f
+  metadata.gz: 527752082a31d6d62e5ea90f3b25cf963fd9721e661419d9c7b217b5bdbea56d36cf77fa29df07a95b5006ff36b772aa3b299d170512641cee1f612b77bbc230
+  data.tar.gz: 919552b28b752e4ffca7c29390b937f618a87b71779afbc0166a01d438d397521dfaf2e414697f860699eb5640d9f216666180ab0f3956cea224f860c778d312

data/Gemfile.lock

@@ -1,26 +1,27 @@
 PATH
   remote: .
   specs:
-    period (0.1.4)
-      activesupport (= 5.2.3)
-      i18n (= 1.6.0)
+    smart-period (1.0.6)
+      activesupport (>= 5, < 7)
+      i18n (~> 1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.3)
+    activesupport (6.1.0)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    concurrent-ruby (1.1.6)
-    i18n (1.6.0)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    concurrent-ruby (1.1.7)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    minitest (5.14.1)
+    minitest (5.14.2)
     rake (10.5.0)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
@@ -28,7 +29,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.0)
   rake (~> 10.0)
-  period!
+  smart-period!
 
 BUNDLED WITH
-   2.0.1
+   2.1.2

data/README.md

@@ -1,8 +1,6 @@
-# Period
+# Smart-Period [![Gem Version](https://badge.fury.io/rb/smart-period.svg)](https://badge.fury.io/rb/smart-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)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/period`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Smart-Period aims to simplify Time-range manipulation. 
 
 ## Installation
 
@@ -22,17 +20,246 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+**Smart-Period** 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
+- **Smart-Period** 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 'period'
+
+# Get all user created today
+User.where(created_at: Period.today)
+
+# Get how many weeks there is from the beginning of time ?
+Period.new('01/01/1970'..Time.now).weeks.count
+
+# Is Trump still in charge ?
+Time.now.in? Period.new('20/01/2017'...'20/01/2021')
+
+# Get the week of an arbitrary date
+Period.week('24/04/1990')
+
+# Write a date for me (I18n supported)
+Period.new('20/01/2017'...'20/01/2021').to_s
+=> "From the 20 January 2017 to the 19 January 2021 included"
+```
+
+## 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)
+# or in a rails Controller with params
+Period.new(params[:start_date]..params[:end_date])
+```
+
+**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')
+```
+
+### Standard Period 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
+Period::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 close period 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`    
+These methods return an array of **StandardPeriod** who are overlapping the current period
+
+| 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    |       |
+
+#### Example
+```ruby
+# Get how many weeks there is from the beginning of time ?
+Period.new('01/01/1970'..Time.now).weeks.count
+# How many day in the current quarter
+Period.this_quarter.days.count
+# Get all the quarters overlapping a Period of time
+Period.new(...).quarters
+```
+
+## 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 first day, of the last week, of the second month, of the current year
+Period.this_year.months.second.weeks.last.days.first
+```
+
+## ActiveRecord
+
+As **Period** inherite from **Range**, you can natively use them in **ActiveRecord** query
+
+```ruby
+# Get all book published this year
+Book.where(published_at: Period.this_year)
+```
+
+## Rails Controller
+
+In a Controller, use the error handling to validate the date for you
+
+```ruby
+class BookController < ApplicationController
+  def between # match via GET and POST
+    # Default value for the range in GET context
+    params[:from] ||= 1.month.ago
+    params[:to]   ||= Time.now
+
+    begin
+      # Retrieve books from the DB
+      @books = Book.where(published: Period.new(params[:from]..params[:to]))
+    rescue ArgumentError => e
+      # Period will handle mis-formatted date and incoherent period
+      # I18n is support 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'
+#=> 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|
+    "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
+
+## TimeZone
+
+Time zone are supported, you have nothing to do   
+If you change the global `Time.zone` of your app, you have nothing to do    
+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
 
-## Development
+## Bug reports
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+If you discover any bugs, feel free to create an [issue on GitHub](https://github.com/billaul/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
 
-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](https://rubygems.org).
+No issues will be addressed outside GitHub
 
-## Contributing
+## Maintainer
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/period.
+* Myself (https://github.com/billaul)
 
 ## License
 

data/{locales → config/locales}/en.yml

@@ -6,6 +6,7 @@ en:
       end_date_is_invalid:        The end date is invalid
       start_is_greater_than_end:  The start date is greater than the end date
       incomparable_error:         Cannot compare Arguments
+      param_must_be_a_range:      The parameter must inherit from the Range class
     standard_period:
       date_is_invalid:            The date is invalid
       day:

data/{locales → config/locales}/fr.yml

@@ -7,6 +7,7 @@ fr:
       start_is_greater_than_end:  Date de début supérieur à la date de fin
       incomparable_error:         Les arguments ne sont pas comparables
       must_implement_to_datetime: L'argument doit repondre a "to_datetime"
+      param_must_be_a_range:      Le paramètre doit hériter de la class Range
     standard_period:
       day:
         default_format: '%{wday} %{day} %{month} %{year}'
@@ -18,3 +19,26 @@ fr:
         default_format: '%{quarter_nb} semestre %{year}'
       year:
         default_format: '%{year}'
+  date:
+    month_names:
+    -
+    - janvier
+    - février
+    - mars
+    - avril
+    - mai
+    - juin
+    - juillet
+    - août
+    - septembre
+    - octobre
+    - novembre
+    - décembre
+    day_names:
+    - dimanche
+    - lundi
+    - mardi
+    - mercredi
+    - jeudi
+    - vendredi
+    - samedi

data/lib/period.rb

@@ -1,7 +1,7 @@
 require_relative 'period/version.rb'
 require 'active_support/all'
 require 'i18n'
-
+require_relative 'numeric.rb'
 require_relative 'period/free_period.rb'
 require_relative 'period/day.rb'
 require_relative 'period/week.rb'
@@ -34,8 +34,8 @@ module Period
         Object.const_get("Period::#{period.capitalize}").new(date)
       end
 
-      define_method period.to_s do
-        Object.const_get("Period::#{period.capitalize}")
+      define_method period.to_s do |range|
+        Object.const_get("Period::#{period.capitalize}").new(range)
       end
     end
 
@@ -50,10 +50,10 @@ module Period
 
       case last_next
       when 'last'
-        from = env_time.now
-        from -= 1.send(klass) unless method_name.match?(/from_now$/)
-        from = from.send("beginning_of_#{klass}")
-        to = count.to_i.send(klass).ago.send("end_of_#{klass}")
+        from = count.to_i.send(klass).ago.send("beginning_of_#{klass}")
+        to = env_time.now
+        to -= 1.send(klass) unless method_name.match?(/from_now$/)
+        to = to.send("end_of_#{klass}")
       when 'next'
         from = env_time.now
         from += 1.send(klass) unless method_name.match?(/from_now$/)

data/lib/period/free_period.rb

@@ -5,9 +5,6 @@ require_relative 'has_many/months.rb'
 require_relative 'has_many/quarters.rb'
 require_relative 'has_many/years.rb'
 
-I18n.load_path << 'locales/fr.yml'
-I18n.load_path << 'locales/en.yml'
-
 class Period::FreePeriod < Range
   include Comparable
 
@@ -18,15 +15,16 @@ class Period::FreePeriod < Range
   include Period::HasMany::Years
 
   def initialize(range)
+    raise ::ArgumentError, I18n.t(:param_must_be_a_range, scope: %i[period free_period]) unless range.class.ancestors.include?(Range)
     from = range.first
     to = range.last
 
     from = time_parse(range.first, I18n.t(:start_date_is_invalid, scope: %i[period free_period])).beginning_of_day
     to = time_parse(range.last, I18n.t(:end_date_is_invalid, scope: %i[period free_period])).end_of_day
-
+    to = to.prev_day if range.exclude_end?
     raise ::ArgumentError, I18n.t(:start_is_greater_than_end, scope: %i[period free_period]) if from > to
 
-    super(from, to, range.exclude_end?)
+    super(from, to)
   end
 
   alias from first
@@ -44,10 +42,6 @@ class Period::FreePeriod < Range
     raise NotImplementedError
   end
 
-  def self.from_date(_date)
-    raise NotImplementedError
-  end
-
   def include?(other)
     if other.class.in?([DateTime, Time, ActiveSupport::TimeWithZone])
       from.to_i <= other.to_i && other.to_i <= to.to_i
@@ -74,8 +68,22 @@ class Period::FreePeriod < Range
     days.count.days
   end
 
-  def -(other)
-    self.class.new((from - other)..(to - other))
+  def -(duration)
+    self.class.new((from - duration)..(to - duration))
+  end
+
+  def +(duration)
+    self.class.new((from + duration)..(to + duration))
+  end
+
+  def ==(other)
+    raise ArgumentError unless other.class.ancestors.include?(Period::FreePeriod)
+
+    from == other.from && to == other.to
+  end
+
+  def strftime(format)
+    to_s(format: format)
   end
 
   def to_s(format: '%d %B %Y')

data/lib/period/has_many/weeks.rb

@@ -4,7 +4,6 @@ module Period
     # @note when include this module provide itterable access to the weeks of
     # the FreePeriod
     module Weeks
-      # TODO, rewrite this to respect ISO %V %G
       def weeks
         @weeks ||= []
         return @weeks if @weeks.present?

data/lib/period/standard_period.rb

@@ -41,12 +41,6 @@ module Period
       self.class.new(to + duration)
     end
 
-    def ==(other)
-      raise ArgumentError unless other.class.ancestors.include?(Period::FreePeriod)
-
-      from == other.from && to == other.to
-    end
-
     def iso_date
       from
     end

data/lib/period/version.rb

@@ -1,5 +1,5 @@
 module Period
 
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.0.7'.freeze
 
 end

data/period.gemspec

@@ -6,10 +6,9 @@ Gem::Specification.new do |spec|
   spec.name          = 'smart-period'
   spec.version       = Period::VERSION
   spec.authors       = ['billau_l']
-  spec.email         = ['billau_l@modulotech.fr']
 
   spec.summary       = 'Manage time ranges without brain damage.'
-  spec.description   = "Period.new('01/01/2020'..Time.now)"
+  # spec.description   = "Period.new('01/01/2020'..Time.now)"
   spec.homepage      = "https://github.com/billaul/period"
   spec.license       = 'MIT'
 
@@ -18,8 +17,10 @@ Gem::Specification.new do |spec|
   if spec.respond_to?(:metadata)
     # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
-    spec.metadata["homepage_uri"] = spec.homepage
-    # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
+    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 " \
@@ -33,10 +34,11 @@ Gem::Specification.new do |spec|
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = %w[lib locals]
+  spec.require_paths = %w[lib]
 
-  spec.add_runtime_dependency 'activesupport', '5.2.3'
-  spec.add_runtime_dependency 'i18n', '1.6.0'
+  spec.required_ruby_version = '> 2.5'
+  spec.add_runtime_dependency 'activesupport', '>= 5', '< 7'
+  spec.add_runtime_dependency 'i18n', '~> 1'
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 10.0'
 end

metadata

@@ -1,43 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: smart-period
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.7
 platform: ruby
 authors:
 - billau_l
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-07 00:00:00.000000000 Z
+date: 2021-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 5.2.3
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 5.2.3
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.0
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.0
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -66,9 +72,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: Period.new('01/01/2020'..Time.now)
+description:
 email:
-- billau_l@modulotech.fr
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -81,6 +86,8 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- config/locales/en.yml
+- config/locales/fr.yml
 - lib/.DS_Store
 - lib/numeric.rb
 - lib/period.rb
@@ -103,24 +110,24 @@ files:
 - lib/period/version.rb
 - lib/period/week.rb
 - lib/period/year.rb
-- locales/en.yml
-- locales/fr.yml
 - period.gemspec
 homepage: https://github.com/billaul/period
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/billaul/period/issues
   homepage_uri: https://github.com/billaul/period
+  documentation_uri: https://github.com/billaul/period
+  source_code_uri: https://github.com/billaul/period
 post_install_message:
 rdoc_options: []
 require_paths:
 - lib
-- locals
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="