xduration 2.2.1

data/.gitignore

@@ -0,0 +1,12 @@
+Gemfile.lock
+.DS_Store
+.idea
+.bundle
+*~
+#*
+*.gem
+.yardoc/*
+coverage/*
+doc/*
+pkg/*
+bluecloth/*

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - ruby-head
+  - jruby-head
+  - ree

data/CHANGELOG

@@ -0,0 +1,8 @@
+## 0.2.2
+
+* Renamed to 'xduration'
+* Added months (30 days) and years (365.25 days)
+* Added month and year I18n support
+* Added Rails engine in order to support auto-load of duration locale files
+* Added numeric macros
+* Added TimeUnit wrappers such as: Hours, Weeks etc.

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in xduration.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Jose Peleteiro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+xduration
+=============
+
+Duration is an immutable type that represents some amount of time with accuracy in seconds.
+
+A lot of the code and inspirations is borrowed from [duration](http://rubyforge.org/projects/duration) 
+lib, which is a **mutable** Duration type with lot more features but lack of tests.
+
+
+Features
+--------
+
+  * Representation of time in weeks, days, hours, minutes and seconds.
+  * Construtor can receive the amount of time in seconds or a Hash with unit and amount of time.
+  * Format method to display the time with i18n support.
+  * Mongoid serialization support. Use `require 'duration/mongoid'`.
+  * Tested on mri 1.8.7, ree 1.8.7, mri 1.9.2, jruby and rubinius. Kudos to rvm!
+
+Extras
+---------
+
+### Macros
+
+`require 'duration/macros'`
+
+```ruby
+1.day + 4.hours
+10.am
+```
+
+`require 'duration/time_units'`
+
+```ruby
+weeks = Weeks.new(6)
+years = Years.new(6)
+```
+
+
+Show me the code
+----------------
+
+### constructor
+
+    Duration.new(100) => #<Duration: minutes=1, seconds=40, total=100>
+    Duration.new(:hours => 5, :minutes => 70) => #<Duration: hours=6, minutes=10, total=22200>
+
+### format
+
+    Duration.new(:weeks => 3, :days => 1).format("%w %~w and %d %~d") => "3 weeks and 1 day"
+    Duration.new(:weeks => 1, :days => 20).format("%w %~w and %d %~d") => "3 weeks and 6 days"
+
+### iso 8601 [more info](http://en.wikipedia.org/wiki/ISO_8601#Durations)
+
+    Duration.new(:weeks => 1, :days => 20).iso8601 => "P3W6DT0H0M0S"
+
+### Mongoid support
+The current version of this gem supports Mongoid >= [2.1.0](https://github.com/mongoid/mongoid). 
+
+    require 'duration/mongoid'
+
+    class MyModel
+      include Mongoid::Document
+      field :duration, type => Duration
+    end
+
+
+Note on Patches/Pull Requests
+-----------------------------
+
+  * Fork the project.
+  * Make your feature addition or bug fix.
+  * Add tests for it. This is important so I don't break it in a
+    future version unintentionally.
+  * Commit, do not mess with rakefile, version, or history.
+    (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+  * Send me a pull request. Bonus points for topic branches.
+
+
+License
+---------
+Copyright (c) 2010 Jose Peleteiro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/config/locales/duration/da.yml

@@ -0,0 +1,16 @@
+da:
+  ruby_duration:
+    second: sekond
+    seconds: sekonder
+    minute: minut
+    minutes: minutter
+    hour: time
+    hours: timer
+    day: dag
+    days: dage
+    week: uge
+    weeks: uges
+    month: måned
+    months: måneder
+    year: år
+    years: år

data/config/locales/duration/pt.yml

@@ -0,0 +1,16 @@
+pt:
+  ruby_duration:
+    second: segundo
+    seconds: segundos
+    minute: minuto
+    minutes: minutos
+    hour: hora
+    hours: horas
+    day: dia
+    days: dias
+    week: semana
+    weeks: semanas
+    month: mes
+    months: meses
+    year: ano
+    years: anos

data/lib/duration/fixnum.rb

@@ -0,0 +1,11 @@
+def Fixnum
+  def am
+    raise "AM, number must be 0-12" if self < 0 || self > 12
+    Time.parse("#{self}:00:00")
+  end
+
+  def pm
+    raise "PM, number must be 0-12" if self < 0 || self > 12
+    Time.parse("#{self+12}:00:00")
+  end
+end

data/lib/duration/macros.rb

@@ -0,0 +1,2 @@
+require 'duration/fixnum'
+require 'duration/numeric'

data/lib/duration/mongoid.rb

@@ -0,0 +1,36 @@
+require "#{File.dirname(__FILE__)}/../duration"
+require "mongoid/fields"
+
+# Mongoid serialization support for Duration type.
+module Mongoid
+  module Fields
+    class Duration
+      include Mongoid::Fields::Serializable
+    
+      # Deserialize a Duration given the amount of seconds stored by Mongodb
+      #
+      # @param [Integer, nil] duration in seconds
+      # @return [Duration] deserialized Duration
+      def deserialize(seconds)
+        return if !seconds
+        ::Duration.new(seconds)
+      end
+
+      # Serialize a Duration or a Hash (with duration units) or a amount of seconds to
+      # a BSON serializable type.
+      #
+      # @param [Duration, Hash, Integer] value
+      # @return [Integer] duration in seconds
+      def serialize(value)
+        return if value.blank?
+        if value.is_a?(Hash)
+          value.delete_if{|k, v| v.blank? || !::Duration::UNITS.include?(k.to_sym)}
+          return if value.blank?
+          ::Duration.new(value).to_i
+        elsif value.respond_to?(:to_i)
+          value.to_i
+        end
+      end
+    end
+  end
+end

data/lib/duration/numeric.rb

@@ -0,0 +1,60 @@
+require 'duration/time_units'
+
+class Numeric
+  def duration
+    Duration.new self
+  end
+
+  def dyears
+    self == 1 ? Year.new : Years.new(self)
+  end
+  def dyear
+    self.dyears
+  end
+
+  def dmonths
+    self == 1 ? Month.new : Months.new(self)
+  end
+  def dmonth
+    self.dmonths
+  end
+
+  def dweeks
+    self == 1 ? Week.new : Weeks.new(self)
+  end
+  def dweek
+    self.dweeks
+  end
+
+  def ddays
+    self == 1 ? Day.new : Days.new(self)
+  end
+  def dday
+    self.ddays
+  end
+
+  def dhours
+    self == 1 ? Hour.new : Hours.new(self)
+  end
+  def dhour
+    self.dhours
+  end
+
+  def dminutes
+    self == 1 ? Minute.new : Minutes.new(self)
+  end
+  def dminute
+    self.dminutes
+  end
+
+  def dseconds
+    self == 1 ? Second.new : Seconds.new(self)
+  end
+  def dsecond
+    self.dseconds
+  end
+
+  def is_multiple_of?(num)
+    self % num == 0
+  end
+end

data/lib/duration/rails/engine.rb

@@ -0,0 +1,9 @@
+module RubyDuration 
+	module Rails
+		class Engine < ::Rails::Engine
+			initializer 'duration setup' do
+				I18n.load_path << Dir[Rails.root.join('config', 'locales', 'duration', '*.yml')]
+			end
+		end
+	end
+end

data/lib/duration/time_units/day.rb

@@ -0,0 +1,12 @@
+class Days < Duration
+	def initialize number = 1
+		super(:days => number)
+	end
+end
+
+class Day < Days
+	def initialize
+		super(1)
+	end
+end
+

data/lib/duration/time_units/decade.rb

@@ -0,0 +1,11 @@
+class Decades < Duration
+	def initialize number = 1
+		super(:decaded => number)
+	end
+end
+
+class Decade < Decades
+	def initialize
+		super(1)
+	end
+end

data/lib/duration/time_units/hour.rb

@@ -0,0 +1,12 @@
+class Hours < Duration
+	def initialize number = 1
+		super(:hours => number)
+	end
+end
+
+class Hour < Hours
+	def initialize
+		super(1)
+	end
+end
+

data/lib/duration/time_units/minute.rb

@@ -0,0 +1,12 @@
+class Minutes < Duration
+	def initialize number = 1
+		super(:minutes => number)
+	end
+end
+
+class Minute < Minutes
+	def initialize
+		super(1)
+	end
+end
+

data/lib/duration/time_units/month.rb

@@ -0,0 +1,12 @@
+class Months < Duration
+	def initialize number = 1
+		super(:months => number)
+	end
+end
+
+class Month < Months
+	def initialize
+		super(1)
+	end
+end
+

data/lib/duration/time_units/second.rb

@@ -0,0 +1,11 @@
+class Seconds < Duration
+	def initialize number = 1
+		super(:seconds => number)
+	end
+end
+
+class Second < Seconds
+	def initialize
+		super(1)
+	end
+end

data/lib/duration/time_units/week.rb

@@ -0,0 +1,11 @@
+class Weeks < Duration
+	def initialize number = 1
+		super(:weeks => number)
+	end
+end
+
+class Week < Weeks
+	def initialize
+		super(1)
+	end
+end

data/lib/duration/time_units/year.rb

@@ -0,0 +1,11 @@
+class Years < Duration
+	def initialize number = 1
+		super(:years => number)
+	end
+end
+
+class Year < Years
+	def initialize
+		super(1)
+	end
+end

data/lib/duration/time_units.rb

@@ -0,0 +1,3 @@
+%w{second minute hour day week month year decade}.each do |unit|
+	require "duration/time_units/#{unit}"
+end

data/lib/duration/version.rb

@@ -0,0 +1,3 @@
+class Duration
+  VERSION = "2.2.1"
+end

data/lib/duration.rb

@@ -0,0 +1,240 @@
+# -*- encoding:  utf-8 -*-
+require 'i18n'
+require 'active_support/core_ext'
+
+if defined?(Rails) && Rails::VERSION::STRING >= '3.1'
+  require 'duration/rails/engine' 
+end
+
+# Duration objects are simple mechanisms that allow you to operate on durations
+# of time.  They allow you to know how much time has passed since a certain
+# point in time, or they can tell you how much time something is (when given as
+# seconds) in different units of time measurement.  Durations would particularly
+# be useful for those scripts or applications that allow you to know the uptime
+# of themselves or perhaps provide a countdown until a certain event.
+class Duration
+  include Comparable
+
+  UNITS = [:seconds, :minutes, :hours, :days, :weeks, :months, :years]
+
+  MULTIPLES = {:seconds => 1,
+               :minutes => 60,
+               :hours   => 3600,
+               :days    => 86400,
+               :weeks   => 604800,
+               :months  => 2592000, # 30 days
+               :years   => 31557600, # 365.25 days
+               :second  => 1,
+               :minute  => 60,
+               :hour    => 3600,
+               :day     => 86400,
+               :week    => 604800,
+               :month   => 2592000,
+               :year    => 31557600}
+
+  attr_reader :years, :months, :weeks, :days, :hours, :minutes, :seconds, :total
+
+  # Initialize a duration. 'args' can be a hash or anything else.  If a hash is
+  # passed, it will be scanned for a key=>value pair of time units such as those
+  # listed in the Duration::UNITS array or Duration::MULTIPLES hash.
+  #
+  # If anything else except a hash is passed, #to_i is invoked on that object
+  # and expects that it return the number of seconds desired for the duration.
+  def initialize(args = 0)
+    if args.kind_of?(Hash)
+      @seconds = 0
+      MULTIPLES.each do |unit, multiple|
+        unit = unit.to_sym
+        @seconds += args[unit].to_i * multiple if args.key?(unit)
+      end
+    else
+      @seconds = args.to_i
+    end
+
+    calculate!
+  end
+
+  # Compare this duration to another (or objects that respond to #to_i)
+  def <=>(other)
+    return false unless other.is_a?(Duration)
+    @total <=> other.to_i
+  end
+
+  def +(other)
+    Duration.new(@total + other.to_i)
+  end
+
+  def -(other)
+    Duration.new(@total - other.to_i)
+  end
+
+  def *(other)
+    Duration.new(@total * other.to_i)
+  end
+
+  def /(other)
+    Duration.new(@total / other.to_i)
+  end
+
+  def %(other)
+    Duration.new(@total % other.to_i)
+  end
+  
+  %w(minutes hours days).each do |meth|
+    define_method("total_#{meth}") { @total / MULTIPLES[meth.to_sym] }
+  end
+
+  # Formats a duration in ISO8601.
+  # @see http://en.wikipedia.org/wiki/ISO_8601#Durations
+  def iso8601
+    output = 'P'
+
+    output << "#{weeks}W" if weeks > 0
+    output << "#{days}D" if days > 0
+    if seconds > 0 || minutes > 0 || hours > 0
+      output << 'T'
+      output << "#{hours}H" if hours > 0
+      output << "#{minutes}M" if minutes > 0
+      output << "#{seconds}S" if seconds > 0
+    end
+
+    output
+  end
+
+  # @return true if total is 0
+  def blank?
+    @total == 0
+  end
+
+  # @return true if total different than 0
+  def present?
+    !blank?
+  end
+
+  # Format a duration into a human-readable string.
+  #
+  #   %w   => weeks
+  #   %d   => days
+  #   %h   => hours
+  #   %m   => minutes
+  #   %s   => seconds
+  #   %td  => total days
+  #   %th  => total hours
+  #   %tm  => total minutes
+  #   %ts  => total seconds
+  #   %t   => total seconds
+  #   %H   => zero-padded hours
+  #   %M   => zero-padded minutes
+  #   %S   => zero-padded seconds
+  #   %~s  => locale-dependent "seconds" terminology
+  #   %~m  => locale-dependent "minutes" terminology
+  #   %~h  => locale-dependent "hours" terminology
+  #   %~d  => locale-dependent "days" terminology
+  #   %~w  => locale-dependent "weeks" terminology
+  #   %tdu => total days with locale-dependent unit
+  #   %thu => total hours with locale-dependent unit
+  #   %tmu => total minutes with locale-dependent unit
+  #   %tsu => total seconds with locale-dependent unit
+  #
+  # You can also use the I18n support.
+  # The %~s, %~m, %~h, %~d and %~w can be translated with I18n.
+  # If you are using Ruby on Rails, the support is ready out of the box, so just change your locale file. Otherwise you can try:
+  #
+  #   I18n.load_path << "path/to/your/locale"
+  #   I18n.locale = :your_locale
+  # 
+  # And you must use the following structure (example) for your locale file:
+  #   pt:
+  #     ruby_duration:
+  #       second: segundo
+  #       seconds: segundos
+  #       minute: minuto
+  #       minutes: minutos
+  #       hour: hora
+  #       hours: horas
+  #       day: dia
+  #       days: dias
+  #       week: semana
+  #       weeks: semanas
+  #
+  def format(format_str)
+    identifiers = {
+      'y'  => @years,
+      'o'  => @months,
+      'w'  => @weeks,
+      'd'  => @days,
+      'h'  => @hours,
+      'm'  => @minutes,
+      's'  => @seconds,
+      'ty' => Proc.new { total_years },
+      'to' => Proc.new { total_months },
+      'tw' => Proc.new { total_weeks },
+      'td' => Proc.new { total_days },
+      'th' => Proc.new { total_hours },
+      'tm' => Proc.new { total_minutes },
+      'ts' => @total,
+      't'  => @total,
+      'H'  => @hours.to_s.rjust(2, '0'),
+      'M'  => @minutes.to_s.rjust(2, '0'),
+      'S'  => @seconds.to_s.rjust(2, '0'),
+      '~s' => i18n_for(:second),
+      '~m' => i18n_for(:minute),
+      '~h' => i18n_for(:hour),
+      '~d' => i18n_for(:day),
+      '~w' => i18n_for(:week),
+      '~o' => i18n_for(:month),
+      '~y' => i18n_for(:year),
+      'tyr'=> Proc.new { "#{total_years} #{i18n_for(:total_year)}"},
+      'tmo'=> Proc.new { "#{total_months} #{i18n_for(:total_month)}"},
+      'twk'=> Proc.new { "#{total_weeks} #{i18n_for(:total_week)}"},
+      'tdu'=> Proc.new { "#{total_days} #{i18n_for(:total_day)}"},
+      'thu'=> Proc.new { "#{total_hours} #{i18n_for(:total_hour)}"},
+      'tmu'=> Proc.new { "#{total_minutes} #{i18n_for(:total_minute)}"},
+      'tsu'=> Proc.new { "#{total} #{i18n_for(:total)}"}
+    }
+
+    format_str.gsub(/%?%(y|o|w|d|h|m|s|t([ydhms]u?)?|H|M|S|~(?:s|m|h|d|w|o|y))/) do |match|
+      match['%%'] ? match : (identifiers[match[1..-1]].class == Proc ? identifiers[match[1..-1]].call : identifiers[match[1..-1]])
+    end.gsub('%%', '%')
+  end
+
+  alias_method :to_i, :total
+  alias_method :strftime, :format
+  
+private
+
+  # Calculates the duration from seconds and figures out what the actual
+  # durations are in specific units.  This method is called internally, and
+  # does not need to be called by user code.
+  def calculate!
+    multiples = [MULTIPLES[:years], MULTIPLES[:months], MULTIPLES[:weeks], MULTIPLES[:days], MULTIPLES[:hours], MULTIPLES[:minutes], MULTIPLES[:seconds]]
+    units     = []
+    @total    = @seconds.to_f.round
+    multiples.inject(@total) do |total, multiple|
+      # Divide into largest unit
+      units << total / multiple
+      total % multiple # The remainder will be divided as the next largest
+    end
+
+    # Gather the divided units
+    @years, @months, @weeks, @days, @hours, @minutes, @seconds = units
+  end
+
+  def i18n_for(singular)
+    if singular == :total
+      fn_name = :total
+      singular = :second
+      plural = 'seconds'
+    elsif singular.to_s.start_with?('total_')
+      fn_name = "#{singular}s"
+      singular = singular.to_s['total_'.length..-1]
+      plural = "#{singular}s"
+    else
+      plural = "#{singular}s"
+      fn_name = plural
+    end
+    label = send(fn_name) == 1 ? singular : plural
+
+    I18n.t(label, :scope => :ruby_duration, :default => label.to_s)
+  end
+end