smart-period 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5df770ae3301222917ed286b21cd001dffedfabcbcd957b7645231a85dac6ea9
-  data.tar.gz: bd565e152c142c751229ff4e3fd8f17f0085f6445722902fb9ba5fe75af4ddf4
+  metadata.gz: bd9b91f3f8553c817029a58445250a56093cc07ea8eb856c88798d5afd72d210
+  data.tar.gz: e5a67dcedd0eae2113f489f46a472cf1b8b4be45caacc1d8910acc59f70be2a5
 SHA512:
-  metadata.gz: eef66c5e59a8054c20647d74cd7beb3749f6683fe359dd7f7effc31c2d659c624a3277b5378039089fd494175515d64cd77eb8a29e8a3ee3917bda65ec708b31
-  data.tar.gz: 737039391b6228fccabf86725e55e75aa0381044ffbd7d7887d9b480d264ccbaa3b4fcead214efbdbfaa83a24c334818c365cd276140302c2a14f0a11a15de5f
+  metadata.gz: ea9f3a5074c20e26c9e8718c91263b993bdef3a9e6b8f9b28015d60c67947a403fad37d2f51322f4053f87ca0590973084461a290515dd592a7eb677253dd599
+  data.tar.gz: c703f75c931446e9114d06bacb43f0d613e38a5d21b03721d25d2e1e0b0bef1cb74b29cc73f2df1e7170b48fab6a30ddccda40d58a2f23c85e446616e5e3da6f

data/README.md

@@ -1,8 +1,6 @@
-# Period
+# Smart-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,189 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+**Smart-Period** was designed to simplify time-range manipulation, specialy with rails 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 smaller-periods
 
-## Development
+**FreePeriod** and some **StandardPeriod** respond to `.days`, `.weeks`, `.months`, `.quarters` and `.years`    
+These methods return an array of **StandardPeriod** who are include inside the current period
 
-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.
+| 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
+```
+
+### BelongsTo greater-period
+
+**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)
+```
+
+### 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"
+```
+
+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
+```
 
-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).
+### Bug reports
 
-## Contributing
+If you discover any bugs, feel free to create an issue on GitHub. 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.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/period.
+https://github.com/billaul/period/issues
 
 ## 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/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.3'.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

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   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 +18,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 " \
@@ -35,8 +37,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = %w[lib locals]
 
+  spec.required_ruby_version = '~> 2.5'
   spec.add_runtime_dependency 'activesupport', '5.2.3'
   spec.add_runtime_dependency 'i18n', '1.6.0'
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rails-i18n', '~> 6.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smart-period
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - billau_l
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-07 00:00:00.000000000 Z
+date: 2020-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -66,7 +66,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: Period.new('01/01/2020'..Time.now)
+- !ruby/object:Gem::Dependency
+  name: rails-i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+description:
 email:
 - billau_l@modulotech.fr
 executables: []
@@ -110,7 +124,10 @@ 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:
@@ -118,9 +135,9 @@ require_paths:
 - 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:
   - - ">="