timerizer 0.0.3 → 0.1.0

data/lib/timerizer.rb

@@ -1,8 +1,7 @@
 require 'date'
 
-# Represents a relative amount of time. For example, `5 days`, `4 years`, and `5 years, 4 hours, 3 minutes, 2 seconds` are all RelativeTimes.
+# Represents a relative amount of time. For example, '`5 days`', '`4 years`', and '`5 years, 4 hours, 3 minutes, 2 seconds`' are all RelativeTimes.
 class RelativeTime
-  # All potential units. Key is the unit name, and the value is its plural form.
   @@units = {
     :second     => :seconds,
     :minute     => :minutes,
@@ -16,7 +15,6 @@ class RelativeTime
     :millennium => :millennia
   }
 
-  # Unit values in seconds. If a unit is not present in this hash, it is assumed to be in the {@@in_months} hash.
   @@in_seconds = {
       :second => 1,
       :minute => 60,
@@ -25,7 +23,6 @@ class RelativeTime
       :week   => 604800
   }
 
-  # Unit values in months. If a unit is not present in this hash, it is assumed to be in the {@@in_seconds} hash.
   @@in_months = {
     :month      => 1,
     :year       => 12,
@@ -40,6 +37,69 @@ class RelativeTime
     :year  => 31556952
   }
 
+  # Default syntax formats that can be used with #to_s
+  # @see #to_s
+  @@syntaxes = {
+    :micro => {
+      :units => {
+        :seconds => 's',
+        :minutes => 'm',
+        :hours => 'h',
+        :days => 'd',
+        :weeks => 'w',
+        :months => 'mn',
+        :years => 'y',
+      },
+      :separator => '',
+      :delimiter => ' ',
+      :count => 1
+    },
+    :short => {
+      :units => {
+        :seconds => 'sec',
+        :minutes => 'min',
+        :hours => 'hr',
+        :days => 'd',
+        :weeks => 'wk',
+        :months => 'mn',
+        :years => 'yr',
+        :centuries => 'ct',
+        :millenia => 'ml'
+      },
+      :separator => '',
+      :delimiter => ' ',
+      :count => 2
+    },
+    :long => {
+      :units => {
+        :seconds => ['second', 'seconds'],
+        :minutes => ['minute', 'minutes'],
+        :hours => ['hour', 'hours'],
+        :days => ['day', 'days'],
+        :weeks => ['week', 'weeks'],
+        :months => ['month', 'months'],
+        :years => ['year', 'years'],
+        :centuries => ['century', 'centuries'],
+        :millennia => ['millenium', 'millenia'],
+      }
+    }
+  }
+
+  # All potential units. Key is the unit name, and the value is its plural form.
+  def self.units
+    @@units
+  end
+
+  # Unit values in seconds. If a unit is not present in this hash, it is assumed to be in the {@@in_months} hash.
+  def self.units_in_seconds
+    @@in_seconds
+  end
+
+  # Unit values in months. If a unit is not present in this hash, it is assumed to be in the {@@in_seconds} hash.
+  def self.units_in_months
+    @@in_months
+  end
+
   # Initialize a new instance of RelativeTime.
   # @overload new(hash)
   #   @param [Hash] units The base units to initialize with
@@ -47,21 +107,20 @@ class RelativeTime
   #   @option units [Fixnum] :months The number of months
   # @overload new(count, unit)
   #   @param [Fixnum] count The number of units to initialize with
-  #   @param [Symbol] unit The unit to initialize. See {@@units}
+  #   @param [Symbol] unit The unit to initialize. See {RelativeTime#units}
   def initialize(count = 0, unit = :second)
-    if(count.is_a? Hash)
-      @seconds = count[:seconds] || 0
-      @months = count[:months] || 0
-      return
-    end
-
-    @seconds = 0
-    @months = 0
+    if count.is_a? Hash
+      units = count
+      units.default = 0
+      @seconds, @months = units.values_at(:seconds, :months)
+    else
+      @seconds = @months = 0
 
-    if(@@in_seconds.has_key?(unit))
-      @seconds = count * @@in_seconds.fetch(unit)
-    elsif(@@in_months.has_key?(unit))
-      @months = count * @@in_months.fetch(unit)
+      if @@in_seconds.has_key?(unit)
+        @seconds = count * @@in_seconds.fetch(unit)
+      elsif @@in_months.has_key?(unit)
+        @months = count * @@in_months.fetch(unit)
+      end
     end
   end
 
@@ -70,8 +129,11 @@ class RelativeTime
   # @return [Boolean] True if both RelativeTimes are equal
   # @note Be weary of rounding; this method compares both RelativeTimes' base units
   def ==(time)
-    raise ArgumentError unless time.is_a?(RelativeTime)
-    return @seconds == time.get(:seconds) && @months == time.get(:months)
+    if time.is_a?(RelativeTime)
+      @seconds == time.get(:seconds) && @months == time.get(:months)
+    else
+      false
+    end
   end
 
   # Return the number of base units in a RelativeTime.
@@ -79,16 +141,20 @@ class RelativeTime
   # @return [Fixnum] The requested unit count
   # @raise [ArgumentError] Unit requested was not :seconds or :months
   def get(unit)
-    return @seconds if unit == :seconds
-    return @months if unit == :months
-    raise ArgumentError
+    if unit == :seconds
+      @seconds
+    elsif unit == :months
+      @months
+    else
+      raise ArgumentError
+    end
   end
 
   # Determines the time between RelativeTime and the given time.
   # @param [Time] time The initial time.
   # @return [Time] The difference between the current RelativeTime and the given time
   # @example 5 hours before January 1st, 2000 at noon
-  #   5.minutes.before(Time.now(2000, 1, 1, 12, 00, 00))
+  #   5.minutes.before(Time.new(2000, 1, 1, 12, 00, 00))
   #     => 2000-01-01 11:55:00 -0800
   # @see #ago
   # @see #after
@@ -102,7 +168,7 @@ class RelativeTime
       new_month += 12
       new_year -= 1
     end
-    if(Date.valid_date?(new_year, new_month, time.day))
+    if Date.valid_date?(new_year, new_month, time.day)
       new_day = time.day
     else
       new_day = Date.new(new_year, new_month).days_in_month
@@ -135,7 +201,7 @@ class RelativeTime
       new_year += 1
       new_month -= 12
     end
-    if(Date.valid_date?(new_year, new_month, time.day))
+    if Date.valid_date?(new_year, new_month, time.day)
       new_day = time.day
     else
       new_day = Date.new(new_year, new_month).days_in_month
@@ -161,9 +227,9 @@ class RelativeTime
     superior_unit = @@units.keys.index(unit) + 1
 
     define_method(in_method) do
-      if(@@in_seconds.has_key?(unit))
+      if @@in_seconds.has_key?(unit)
         @seconds / @@in_seconds[unit]
-      elsif(@@in_months.has_key?(unit))
+      elsif @@in_months.has_key?(unit)
         @months / @@in_months[unit]
       end
     end
@@ -173,7 +239,7 @@ class RelativeTime
       count_superior = @@units.keys[superior_unit]
 
       time = self.send(in_method)
-      if(@@units.length > superior_unit)
+      if @@units.length > superior_unit
         time -= self.send(in_superior).send(count_superior).send(in_method)
       end
       time
@@ -188,14 +254,16 @@ class RelativeTime
   # @see #average!
   # @see #unaverage
   def average
-    return self unless @seconds > 0
-
-    months = (@seconds / @@average_seconds[:month])
-    seconds = @seconds - months.months.unaverage.get(:seconds)
-    RelativeTime.new({
-      :seconds => seconds,
-      :months => months + @months
-    })
+    if @seconds > 0
+      months = (@seconds / @@average_seconds[:month])
+      seconds = @seconds - months.months.unaverage.get(:seconds)
+      RelativeTime.new(
+        :seconds => seconds,
+        :months => months + @months
+      )
+    else
+      self
+    end
   end
 
   # Destructively average second-based units to month-based units.
@@ -217,7 +285,7 @@ class RelativeTime
   def unaverage
     seconds = @@average_seconds[:month] * @months
     seconds += @seconds
-    RelativeTime.new({:seconds => seconds})
+    RelativeTime.new(:seconds => seconds)
   end
 
   # Destructively average month-based units to second-based units.
@@ -251,32 +319,252 @@ class RelativeTime
     })
   end
 
+  # Converts {RelativeTime} to {WallClock}
+  # @return [WallClock] {RelativeTime} as {WallClock}
+  # @example
+  #   (17.hours 30.minutes).to_wall
+  #     # => 5:30:00 PM
+  def to_wall
+    raise WallClock::TimeOutOfBoundsError if @months > 0
+    WallClock.new(:second => @seconds)
+  end
+
   # Convert {RelativeTime} to a human-readable format.
+  # @overload to_s(syntax)
+  #   @param [Symbol] syntax The syntax from @@syntaxes to use
+  # @overload to_s(hash)
+  #   @param [Hash] hash The custom hash to use
+  #   @option hash [Hash] :units The unit names to use. See @@syntaxes for examples
+  #   @option hash [Fixnum] :count The maximum number of units to output. `1` would output only the unit of greatest example (such as the hour value in `1.hour 3.minutes 2.seconds`).
+  #   @option hash [String] :separator The separator to use in between a unit and its value
+  #   @option hash [String] :delimiter The delimiter to use in between different unit-value pairs
   # @example
   #   (14.months 49.hours).to_s
   #     => 2 years, 2 months, 3 days, 1 hour
-  def to_s
-    times = [] 
+  #   (1.day 3.hours 4.minutes).to_s(:short)
+  #     => 1d 3hr
+  # @raise KeyError Symbol argument isn't in @@syntaxes
+  # @raise ArgumentError Argument isn't a hash (if not a symbol)
+  # @see @@syntaxes
+  def to_s(syntax = :long)
+    if syntax.is_a? Symbol
+      syntax = @@syntaxes.fetch(syntax)
+    end
 
-    @@units.each do |unit, plural|
-      time = self.respond_to?(plural) ? self.send(plural) : 0
-      times << [time, (time != 1) ? plural : unit] if time > 0
+    raise ArgumentError unless syntax.is_a? Hash
+    times = []
+
+    if syntax[:count].nil? || syntax[:count] == :all
+      syntax[:count] = @@units.count
+    end
+    units = syntax.fetch(:units)
+
+    count = 0
+    units = Hash[units.to_a.reverse]
+    units.each do |unit, (singular, plural)|
+      if count < syntax.fetch(:count)
+        time = self.respond_to?(unit) ? self.send(unit) : 0
+
+        if time > 1 && !plural.nil?
+          times << [time, plural]
+          count += 1
+        elsif time > 0
+          times << [time, singular]
+          count += 1
+        end
+      end
     end
 
     times.map do |time|
-      time.join(' ')
-    end.reverse.join(', ')
+      time.join(syntax[:separator] || ' ')
+    end.join(syntax[:delimiter] || ', ')
+  end
+end
+
+# Represents a time, but not a date. '`7:00 PM`' would be an example of a WallClock object
+class WallClock
+  # Represents an error where an invalid meridiem was passed to WallClock.
+  # @see #new
+  class InvalidMeridiemError < ArgumentError; end
+  # Represents an error where a time beyond 24 hours was passed to WallClock.
+  # @see #new
+  class TimeOutOfBoundsError < ArgumentError; end
+
+  # Initialize a new instance of WallClock
+  # @overload new(hash)
+  #   @param [Hash] units The units to initialize with
+  #   @option units [Fixnum] :hour The hour to initialize with
+  #   @option units [Fixnum] :minute The minute to initialize with
+  #   @option units [Fixnum] :second The second to initialize with
+  # @overload new(hour, minute, meridiem)
+  #   @param [Fixnum] hour The hour to initialize with
+  #   @param [Fixnum] minute The minute to initialize with
+  #   @param [Symbol] meridiem The meridiem to initialize with (`:am` or `:pm`)
+  # @overload new(hour, minute, second, meridiem)
+  #   @param [Fixnum] hour The hour to initialize with
+  #   @param [Fixnum] minute The minute to initialize with
+  #   @param [Fixnum] second The second to initialize with
+  #   @param [Symbol] meridiem The meridiem to initialize with (`:am` or `:pm`)
+  # @raise InvalidMeridiemError Meridiem is not `:am` or `:pm`
+  def initialize(hour = 0, minute = 0, second = 0, meridiem = :am)
+    if hour.is_a?(Hash)
+      units = hour
+
+      second = units[:second] || 0
+      minute = units[:minute] || 0
+      hour = units[:hour] || 0
+    else
+      if second.is_a?(String) || second.is_a?(Symbol)
+        meridiem = second
+        second = 0
+      end
+
+      meridiem = meridiem.downcase.to_sym
+      if !(meridiem == :am || meridiem == :pm)
+        raise InvalidMeridiemError
+      elsif meridiem == :pm && hour > 12
+        raise TimeOutOfBoundsError, "hour must be <= 12 for PM"
+      elsif hour >= 24 || minute >= 60 || second >= 60
+        raise TimeOutOfBoundsError
+      end
+
+      hour += 12 if meridiem == :pm
+    end
+
+    @seconds =
+      RelativeTime.units_in_seconds.fetch(:hour) * hour +
+      RelativeTime.units_in_seconds.fetch(:minute) * minute +
+      second
+
+    if @seconds >= RelativeTime.units_in_seconds.fetch(:day)
+      raise TimeOutOfBoundsError
+    end
+  end
+
+  # Returns the time of the WallClock on a date
+  # @param [Date] date The date to apply the time on
+  # @return [Time] The time after the given date
+  # @example yesterday at 5:00
+  #   time = WallClock.new(5, 00, :pm)
+  #   time.on(Date.yesterday)
+  #     => 2000-1-1 17:00:00 -0800
+  def on(date)
+    date.to_date.to_time + @seconds
+  end
+
+  # Comparse two {WallClock}s.
+  # @return [Boolean] True if the WallClocks are identical
+  def ==(time)
+    if time.is_a? WallClock
+      self.in_seconds == time.in_seconds
+    else
+      false
+    end
+  end
+
+  # Get the time of the WallClock, in seconds
+  # @return [Fixnum] The total time of the WallClock, in seconds
+  def in_seconds
+    @seconds
+  end
+
+  # Get the time of the WallClock, in minutes
+  # @return [Fixnum] The total time of the WallClock, in minutes
+  def in_minutes
+    @seconds / RelativeTime.units_in_seconds[:minute]
+  end
+
+  # Get the time of the WallClock, in hours
+  # @return [Fixnum] The total time of the WallClock, in hours
+  def in_hours
+    @seconds / RelativeTime.units_in_seconds[:hour]
+  end
+
+  # Get the second of the WallClock.
+  # @return [Fixnum] The second component of the WallClock
+  def second
+    self.to_relative.seconds
+  end
+
+  # Get the minute of the WallClock.
+  # @return [Fixnum] The minute component of the WallClock
+  def minute
+    self.to_relative.minutes
+  end
+
+  # Get the hour of the WallClock.
+  # @param [Symbol] system The houring system to use (either `:twelve_hour` or `:twenty_four_hour`; default `:twenty_four_hour`)
+  # @return [Fixnum] The hour component of the WallClock
+  def hour(system = :twenty_four_hour)
+    hour = self.to_relative.hours
+    if (system == :twelve_hour) && hour > 12
+      hour - 12
+    elsif (system == :twenty_four_hour)
+      hour
+    else
+      raise ArgumentError, "system should be :twelve_hour or :twenty_four_hour"
+    end
+  end
+
+  # Get the meridiem of the WallClock.
+  # @return [Symbol] The meridiem (either `:am` or `:pm`)
+  def meridiem
+    if self.hour > 12
+      :pm
+    else
+      :am
+    end
+  end
+
+  # Converts self to {WallClock}
+  # @see Time#to_wall
+  def to_wall
+    self
+  end
+
+  # Converts {WallClock} to {RelativeTime}
+  # @return [RelativeTime] {WallClock} as {RelativeTime}
+  # @example
+  #   time = WallClock.new(5, 30, :pm)
+  #   time.to_relative
+  #     => 5 hours, 30 minutes
+  def to_relative
+    @seconds.seconds
+  end
+
+  # Convert {WallClock} to a human-readable format.
+  # @param [Symbol] system The hour system to use (`:twelve_hour` or `:twenty_four_hour`; default `:twelve_hour`)
+  # @example
+  #   time = WallClock.new(5, 37, :pm)
+  #   time.to_s
+  #     => "5:37:00 PM"
+  #   time.to_s(:twenty_four_hour)
+  #     => "17:37:00"
+  # @raise ArgumentError Argument isn't a proper system
+  def to_s(system = :twelve_hour)
+    if(system == :twelve_hour)
+      meridiem = self.meridiem.to_s.upcase
+      "#{self.hour(system)}:#{self.minute}:#{self.second} #{meridiem}"
+    elsif(system == :twenty_four_hour)
+      "#{self.hour(system)}:#{self.minute}:#{self.second}"
+    else
+      raise ArgumentError, "system should be :twelve_hour or :twenty_four_hour"
+    end
   end
 end
 
 # {Time} class monkeywrenched with {RelativeTime} support.
 class Time
-  class TimeIsInThePastException < Exception; end
-  class TimeIsInTheFutureException < Exception; end
+  # Represents an error where two times were expected to be in the future, but were in the past.
+  # @see #until
+  class TimeIsInThePastError < ArgumentError; end
+  # Represents an error where two times were expected to be in the past, but were in the future.
+  # @see #since
+  class TimeIsInTheFutureError < ArgumentError; end
 
   add = instance_method(:+)
   define_method(:+) do |time|
-    if(time.class == RelativeTime)
+    if time.is_a? RelativeTime
       time.after(self)
     else
       add.bind(self).(time)
@@ -285,7 +573,7 @@ class Time
 
   subtract = instance_method(:-)
   define_method(:-) do |time|
-    if(time.class == RelativeTime)
+    if time.is_a? RelativeTime
       time.before(self)
     else
       subtract.bind(self).(time)
@@ -302,13 +590,13 @@ class Time
   # @see Time#since
   # @see Time#between
   def self.until(time)
-    raise TimeIsInThePastException if Time.now > time.to_time
+    raise TimeIsInThePastError if Time.now > time.to_time
 
     Time.between(Time.now, time)
   end
 
   # Calculates the time since a given time
-  # @param [Time] since The time to calculate since now
+  # @param [Time] time The time to calculate since now
   # @return [RelativeTime] The time since the provided time
   # @raise[TimeIsInTheFutureException] The provided time is in the future
   # @example
@@ -317,7 +605,7 @@ class Time
   # @see Time#since
   # @see Time#between
   def self.since(time)
-    raise TimeIsInTheFutureException if time.to_time > Time.now
+    raise TimeIsInTheFutureError if time.to_time > Time.now
 
     Time.between(Time.now, time)
   end
@@ -352,6 +640,17 @@ class Time
   def to_time
     self
   end
+
+  # Converts {Time} to {WallClock}
+  # @return [WallClock] {Time} as {WallClock}
+  # @example
+  #   time = Time.now.to_wall
+  #   Date.tomorrow.at(time)
+  #     => 2000-1-2 13:13:27 -0800
+  #     # "Same time tomorrow?"
+  def to_wall
+    WallClock.new(self.hour, self.min, self.sec)
+  end
 end
 
 # {Date} class monkeywrenched with {RelativeTime} helpers.
@@ -377,6 +676,14 @@ class Date
     self
   end
 
+  # Apply a time to a date
+  # @example yesterday at 5:00
+  #   Date.yesterday.at(WallClock.new(5, 00, :pm))
+  #     => 2000-1-1 17:00:00 -0800
+  def at(time)
+    time.to_wall.on(self)
+  end
+
   # Return tomorrow as {Date}.
   # @see Date#yesterday
   def self.tomorrow
@@ -394,10 +701,9 @@ end
 # @example
 #   5.minutes
 #     => 5 minutes
-# @see RelativeTime @@units
+# @see {RelativeTime#units}
 class Fixnum
-  units  = RelativeTime.class_variable_get(:@@units)
-  units.each do |unit, plural|
+  RelativeTime.units.each do |unit, plural|
     define_method(unit) do |added_time = RelativeTime.new|
       time = RelativeTime.new(self, unit)
       time + added_time

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timerizer
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors: