easy_time 0.1.2

data/Rakefile

@@ -0,0 +1,19 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :spec do
+  desc "run tests with code coverage"
+  task :coverage do
+    sh "CODE_COVERAGE=1 bundle exec rake spec"
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.options += ['--title', "EasyTime #{EasyTime::VERSION} Documentation"]
+  t.stats_options = ['--list-undoc']
+end
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "easy_time"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/easy_time.gemspec

@@ -0,0 +1,63 @@
+require_relative 'lib/easy_time/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "easy_time"
+  spec.version       = EasyTime::VERSION
+  spec.authors       = ["Alan Stebbens"]
+  spec.email         = ["aks@stebbens.org"]
+
+  spec.summary       = %q{Easy auto-conversion of most date and time values with tolerant-comparisons}
+  spec.description   =
+    <<~'DESC'
+
+      A class that wraps the Time class and makes it easy to work with most
+      known time values, including various time strings, automatically
+      converting them to Time values, and perform tolerant comparisons.
+      Several time classes, and the String class, are extended with the
+      ".easy_time" method to perform an auto-conversion.  A tolerant comparison
+      allows for times from differing systems to be compared, even when the
+      systems are out of sync, using the relationship operators and methods
+      like "newer?", "older?", "same?" and "between?".  A tolerant comparison
+      for equality is where the difference of two values is less than the
+      tolerance value (1 minute by default).  The tolerance can be configured,
+      even set to zero.  Finally, all of the Time class and instance methods
+      are available on the EasyTime class and instances.
+
+    DESC
+  spec.homepage      = 'https://github.com/aks/easy_time'
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/aks/easy_time"
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # 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('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.1.4"
+  spec.add_development_dependency "fuubar", ">= 2.5.0"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "guard-yard"
+  spec.add_development_dependency "pry-byebug"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec_junit"
+  spec.add_development_dependency "rspec_junit_formatter"
+  spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "rubocop", ">= 0.82.0"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "terminal-notifier-guard" if /Darwin/.match?(`uname -a`.strip)
+  spec.add_development_dependency "yard", ">= 0.9.24"
+
+  spec.add_dependency "activesupport"
+end

data/lib/easy_time.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+require 'active_support'
+require 'active_support/duration'
+require 'active_support/time_with_zone'
+require 'active_support/core_ext/numeric/time'
+
+require 'easy_time/version'
+require 'easy_time/convert'
+
+# Are you tired of having to deal with many kinds of date and time objects?
+#
+# Are you frustrated that comparing timestamps from different systems yields
+# incorrect results?  _(Were you surprised to learn that, despite really good
+# time sync sources, many systems aren't actually synced all that closely in
+# time?)_
+#
+# Well, then, give EasyTime a try!
+#
+# `EasyTime` accepts most of the well-known date and time objects, including
+# `RFC2822`, `HTTPDate`, `XMLSchema`, and `ISO8601` strings and provides
+# comparisons that have an adjustable tolerance.  With `EasyTime` methods, you
+# can reliably compare two timestamps and determine which one is "newer", "older"
+# or the "same" withing a configurable tolerance.  The default comparison
+# tolerance is 1.minute.
+#
+# In other words, if you have a time-stamp from an `ActiveRecord` object that is
+# a few seconds different from a related object obtained from a 3rd-party system,
+# (eg: AWS S3), then logically, from an application perspective, these two
+# objects could be considered having the "same" time-stamp.
+#
+# This is quite useful when one is trying to keep state synchronized between
+# different systems.  How does one know if an object is "newer" or "older" than
+# that from another system?  If the system time from the connected systems varies
+# by a few or more seconds, then comparisons needs to have some tolerance.
+#
+# Having a tolerant comparison makes "newness" and "oldness" checks easier to
+# manage across systems with possibly varying time sources.
+#
+# `EasyTime` objects are just like Time objects, except:
+#
+# - they auto-convert most date and time objects to Time objects
+# - they provide configurable tolerant comparisons between two time objects
+#
+# Even if you decide to set the configurable comparison tolerance to zero
+# _(which disables it)_, the auto-type conversion of most date and time objects
+# makes time and date comparisons and arithmetic very easy.
+#
+# Finally, this module adds an new instance method to the familiar date and
+# time classes, to easily convert from the object to the corresponding
+# `EasyTime` object:
+#
+#     time.easy_time
+#
+# The conversion to an `EasyTime` can also be provided with a tolerance value:
+#
+#     time.easy_time(tolerance: 5.seconds)
+#
+# These are the currently known date and time classes the values of which will
+# be automatically converted to an `EasyTime` value with tolerant comparisons:
+#
+#     Date
+#     Time
+#     EasyTime
+#     DateTime
+#     ActiveSupport::Duration
+#     ActiveSupport::TimeWithZone
+#     String
+#
+# The String values are examined and parsed into a `Time` value.  If a string
+# cannot be parsed, the `new` and `convert` methods return a nil.
+#
+class EasyTime
+  include Comparable
+
+  # we define a default tolerance below.  This causes time value differences
+  # less than this to be considered "equal".  This allows for time comparisons
+  # between values from different systems where the clock sync might not be
+  # very accurate.
+  #
+  # If this default tolerance is not desired, it can be overridden with an
+  # explicit tolerance setting in the singleton class instance:
+  #
+  #   EasyTime.comparison_tolerance = 0
+
+  DEFAULT_TIME_COMPARISON_TOLERANCE = 1.minute
+
+  class << self
+    # @example These comparison methods observe the comparison tolerance
+    #
+    #    EasyTime.newer?(t1, t2, tolerance: nil)  # => true if t1 > t2
+    #    EasyTime.older?(t1, t2, tolerance: nil)  # => true if t1 < t2
+    #    EasyTime.same?(t1, t2, tolerance: nil)   # => true if t1 == t2
+    #    EasyTime.compare(t1, t2, tolerance: nil) # => -1, 0, 1 (or nil)
+    #
+    #  By default, the `tolerance` is nil, which means that any previously
+    #  configured instance comparison tolerance value is used, if it is set,
+    #  otherwise, the class comparison tolerance is used, if it set, otherwise
+    #  the default `DEFAULT_TIME_COMPARISON_TOLERANCE` is used.
+
+    # @param time1 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] a time value
+    # @param time2 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] another time value
+    # @param tolerance [Integer] seconds of tolerance _(optional)_
+    # @return [Boolean] true if `time1` > `time2`, using a tolerant comparison
+
+    def newer?(time1, time2, tolerance: nil)
+      compare(time1, time2, tolerance: tolerance).positive?
+    end
+
+    # @param time1 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] a time value
+    # @param time2 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] another time value
+    # @param tolerance [Integer] seconds of tolerance _(optional)_
+    # @return [Boolean] true if `time1` > `time2`, using a tolerant comparison
+
+    def older?(time1, time2, tolerance: nil)
+      compare(time1, time2, tolerance: tolerance).negative?
+    end
+
+    # @param time1 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] a time value
+    # @param time2 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] another time value
+    # @param tolerance [Integer] seconds of tolerance _(optional)_
+    # @return [Boolean] true if `time1` > `time2`, using a tolerant comparison
+
+    def same?(time1, time2, tolerance: nil)
+      compare(time1, time2, tolerance: tolerance).zero?
+    end
+
+
+    # @overload between?(time1, t_min, t_max, tolerance: nil)
+    #   @param time1 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] a time value
+    #   @param t_min [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] the minimum time
+    #   @param t_max [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] the maximum time
+    #   @return [Boolean] true if `t_min <= time1 <= t_max`, using tolerant comparisons
+    #
+    # @overload between?(time1, time_range, tolerance: nil)
+    #   @param time1 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] a time value
+    #   @param time_range [Range] a range `(t_min..t_max)` of time values
+    #   @return [Boolean] true if `time_range.min <= time1 <= time_range.max`, using tolerant comparisons
+
+    def between?(time1, t_arg, t_max=nil, tolerance: nil)
+      if t_arg.is_a?(Range)
+        t_min = t_arg.min
+        t_max = t_arg.max
+      else
+        t_min = t_arg
+      end
+      compare(time1, t_min, tolerance: tolerance) >= 0 &&
+        compare(time1, t_max, tolerance: tolerance) <= 0
+    end
+
+    # @param time1 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] a time value
+    # @param time2 [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] another time value
+    # @param tolerance [Integer] seconds of tolerance _(optional)_
+    # @return [Integer] one of [-1, 0, 1] if `time1` <, ==, or > than `time2`,
+    #         or nil if `time2` cannot be converted to a `Time` value.
+
+    def compare(time1, time2, tolerance: nil)
+      new(time1, tolerance: tolerance) <=> time2
+    end
+
+    attr_writer :comparison_tolerance
+
+    # Class methods to set the class-level comparison tolerance
+    #
+    # @example
+    #     EasyTime.comparison_tolerance = 0          # turns off any tolerance
+    #     EasyTime.comparison_tolerance = 5.seconds  # makes times within 5 seconds the "same"
+    #     EasyTime.comparison_tolerance = 1.minute   # the default
+
+    # @return [Integer] the number of seconds of tolerance to use for "equality" tests
+    def comparison_tolerance
+      @tolerance || DEFAULT_TIME_COMPARISON_TOLERANCE
+    end
+
+    # @param time_string [String] a time string in one of the many known Time string formats
+    # @return [EasyTime]
+    def parse(time_string)
+      new(parse_string(time_string))
+    end
+
+    def method_missing(name, *args, &block)
+      if Time.respond_to?(name)
+        value = Time.send(name, *args, &block)
+        is_a_time?(value) ? new(value) : value
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_all=false)
+      Time.respond_to?(name, include_all)
+    end
+
+    # @param value [Anything] value to test as a time-like object
+    # @return [Boolean] true if value is one the known Time classes, or responds to :acts_like_time?
+    def is_a_time?(value)
+      case value
+      when Integer, ActiveSupport::Duration
+        false
+      when Date, Time, DateTime, ActiveSupport::TimeWithZone, EasyTime
+        true
+      else
+        value.respond_to?(:acts_like_time?) && value.acts_like_time?
+      end
+    end
+  end
+
+  attr_accessor :time
+  attr_reader   :other_time
+  attr_writer   :comparison_tolerance
+
+  delegate :to_s, :inspect, to: :time
+
+  def initialize(*time, tolerance: nil)
+    @time = time.presence && convert(time.size == 1 ? time.first : time)
+    @comparison_tolerance = tolerance
+  end
+
+  # if there is no instance value, default to the class value
+  def comparison_tolerance
+    @comparison_tolerance || self.class.comparison_tolerance
+  end
+
+  # returns a _new_ EasyTime value with the tolerance set to value
+  #
+  # @example Example:
+  #
+  #    t1 = EasyTime.new(some_time)
+  #    t1.with_tolerance(2.seconds) <= some_other_time
+  #
+  # @param value [Integer] a number of seconds to use as the comparison tolerance
+  # @return [EasyTime] a new EasyTime value with the given tolerance
+
+  def with_tolerance(value)
+    dup.tap { |time| time.comparison_tolerance = value }
+  end
+
+  # @example Comparison examples
+  #    time1 = EasyTime.new(a_time, tolerance: nil)
+  #    time1.newer?(time2)
+  #    time1.older?(time2)
+  #    time1.same?(time2)
+  #    time1.compare(time2) # => -1, 0, 1
+
+  # @param time2 [String,Date,Time,DateTime,Duration,Array<Integer>] another time value
+  # @return [Boolean] true if `self` > `time2`
+
+  def newer?(time2)
+    self > time2
+  end
+
+  # @param time2 [String,Date,Time,DateTime,Duration,Array<Integer>] another time value
+  # @return [Boolean] true if `self` < `time2`
+
+  def older?(time2)
+    self < time2
+  end
+
+  # @param time2 [String,Date,Time,DateTime,Duration,Array<Integer>] another time value
+  # @return [Boolean] true if `self` == `time2`
+
+  def same?(time2)
+    self == time2
+  end
+  alias eql? same?
+
+  # @param time2 [String,Date,Time,DateTime,Duration,Array<Integer>] another time value
+  # @return [Boolean] true if `self` != `time2`
+
+  def different?(time2)
+    self != time2
+  end
+
+  # @param time2 [String,Date,Time,DateTime,Duration,Array<Integer>] another time value
+  # @return [Integer] one of the values: [-1, 0, 1] if `self` [<, ==, >] `time2`,
+  #         or nil if `time2` cannot be converted to a `Time` value
+
+  def compare(time2, tolerance: nil)
+    self.comparison_tolerance = tolerance if tolerance
+    self <=> time2
+  end
+
+  # compare with automatic type-conversion and tolerance
+  # @return [Integer] one of [-1, 0, 1] or nil
+
+  def <=>(other)
+    diff = self - other  # note: this has a side-effect of setting @other_time
+    if diff && diff.abs.to_i <= comparison_tolerance.to_i
+      0
+    elsif diff
+      time <=> other_time
+    end
+  end
+
+  # compare a time against a min and max date pair, or against a time Range value.
+  # @overload between?(t_min, t_max, tolerance: nil)
+  #   @param t_min [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] the minimum time
+  #   @param t_max [Date,Time,DateTime,EasyTime,Duration,String,Array<Integer>] the maximum time
+  #   @param tolerance [Integer] the optional amount of seconds of tolerance to use in the comparison
+  #   @return [Boolean] true if `t_min <= self.time <= t_max`, using tolerant comparisons
+  #
+  # @overload between?(time_range, tolerance: nil)
+  #   @param time_range [Range] a range `(t_min..t_max)` of time values
+  #   @param tolerance [Integer] the optional amount of seconds of tolerance to use in the comparison
+  #   @return [Boolean] true if `time_range.min <= self.time <= time_range.max`, using tolerant comparisons
+
+  def between?(t_arg, t_max = nil)
+    if t_arg.is_a?(Range)
+      t_min = t_arg.min
+      t_max = t_arg.max
+    else
+      t_min = t_arg
+    end
+    compare(t_min) >= 0 && compare(t_max) <= 0
+  end
+
+  # @param duration [Integer] seconds to add to the EasyTime value
+  # @return [EasyTime] updated date and time value
+  def +(duration)
+    dup.tap { |eztime| eztime.time += duration }
+  end
+
+  # Subtract a value from an EasyTime.  If the value is an integer, it is treated
+  # as seconds.  If the value is any of the Date, DateTime, Time, EasyTime, or a String-
+  # formatted date/time, it is subtracted from the EasyTime value resulting in an integer
+  # duration.
+  # @param other [Date,Time,DateTime,EasyTime,Duration,String,Integer]
+  #        a date/time value, a duration, or an Integer
+  # @return [EasyTime,Integer] updated time _(time - duration)_ or duration _(time - time)_
+  def -(other)
+    @other_time = convert(other, false)
+    if is_a_time?(other_time)
+      time - other_time
+    elsif other_time
+      dup.tap { |eztime| eztime.time -= other_time }
+    end
+  end
+
+  def acts_like_time?
+    true
+  end
+
+  private
+
+  def convert(datetime, coerce = true)
+    self.class.convert(datetime, coerce)
+  end
+
+  # intercept any time methods so they can wrap the time-like result in a new EasyTime object.
+  def method_missing(name, *args, &block)
+    if time.respond_to?(name)
+      value = time.send(name, *args, &block)
+      is_a_time?(value) ? dup.tap { |eztime| eztime.time = value } : value
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(method_name, include_all=false)
+    time.respond_to?(name, include_all)
+  end
+
+  def is_a_time?(value)
+    self.class.is_a_time?(value)
+  end
+end
+
+# Extend the known date and time classes _(including EasyTime itself!)_
+module EasyTimeExtensions
+  def easy_time(tolerance: nil)
+    EasyTime.new(self, tolerance: tolerance)
+  end
+end
+
+[EasyTime, Date, Time, DateTime, ActiveSupport::Duration, ActiveSupport::TimeWithZone, String].each do |klass|
+  klass.include(EasyTimeExtensions)
+end
+
+# end of EasyTime