smart-period 1.0.0 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd14ecdd3ede7c4ca9abb4fa8c06abf1a6cf07cc518492f964e607ae43a723ce
-  data.tar.gz: 3245f5e367c91c2d20afa9ca6a90e86f00371a962436fd98a59d3ff97f6307ad
+  metadata.gz: 895c9a0aebae550b0872c4bb281ece79adf6693b019430b4da5ce30ffe0bcf9d
+  data.tar.gz: a1c4024ee3ee06bec4a5499c4d980364fca9ec7fba6f43f8cc8f22abe8978bfc
 SHA512:
-  metadata.gz: 6ca42e1a8a26268ffeb33d04965c4494ffb4b334992e59289ff5c56dedc19ee110a8a2a9f0798cadb69337ea1df8d8670a6ca975058fb8c05ddf5103bd3ff0dd
-  data.tar.gz: 5d728d18e9870ba11c348d3b137cf737f36c9ea57c31df0eb98ae9a3e986a431a0aa503d4784fa0214f2bc6d64e11614b91f523e826feec58625a37382b6bb20
+  metadata.gz: 2c2016a30c249b509ce2ce2dbde28fbb13254c87a261273efdff42e41108a602130d730de96ffda23cab7fa9f114f6a0c9b7d9c0561702ed995230922620ca66
+  data.tar.gz: 3e255e9c615688671dc73fa2cdaad1146e3f8b496c701b4314c0a7340179b57fffdd2d8ca358c9bd3c086fb8562f3d2c4f78c5b09aee5e81f7238ceff13567f4

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.4)
+      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,244 @@ 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
+# 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/lib/period.rb

@@ -1,6 +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'
@@ -34,8 +35,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 +51,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

@@ -18,15 +18,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 +45,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 +71,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,3 +1,5 @@
 module Period
-  VERSION = '1.0.0'.freeze
+
+  VERSION = '1.0.6'.freeze
+
 end

data/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/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/period.gemspec

@@ -6,25 +6,26 @@ 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       = 'Write a short summary, because RubyGems requires one.'
-  spec.description   = 'Write a longer description or delete this line.'
-  # spec.homepage      = "Put your gem's website or public repo URL here."
+  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["homepage_uri"] = spec.homepage
-  #   spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
-  #   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
+  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.
@@ -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 locales]
 
-  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.0
+  version: 1.0.6
 platform: ruby
 authors:
 - billau_l
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-07 00:00:00.000000000 Z
+date: 2020-12-28 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: Write a longer description or delete this line.
+description:
 email:
-- billau_l@modulotech.fr
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -106,20 +111,24 @@ files:
 - locales/en.yml
 - locales/fr.yml
 - period.gemspec
-homepage:
+homepage: https://github.com/billaul/period
 licenses:
 - MIT
-metadata: {}
+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
+- locales
 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:
   - - ">="
@@ -129,5 +138,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
-summary: Write a short summary, because RubyGems requires one.
+summary: Manage time ranges without brain damage.
 test_files: []