blaxter-duration 0.1.4

data/History.txt

@@ -0,0 +1,13 @@
+== 0.1.1
+
+* Numeric#weeks is actually defined this time
+* Default locales aren't assumed for missing constant definitions in other locales
+* migrated to newgem schema
+* removed README, LICENSE, duration.gemspec
+* added Readme.txt, License.txt, Manifest.txt and other newgem files
+* Duration::VERSION is now a module: Duration::VERSION::{MAJOR,MINOR,TINY,STRING}
+* added ::christmas and ::new_years to Time::Holidays
+* added some docs to duration/localizations/english.rb for translators to read
+* added French and Dutch localizations (thanks to Jean-François, Jean-François, Siep Korteling)
+* added Polish localization (thanks to Marcin Raczkowski)
+* added Duration.version which returns Duration::VERSION::STRING

data/License.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2007 Matthew Harris
+
+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/Manifest.txt

@@ -0,0 +1,36 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/duration.rb
+lib/duration/holidays.rb
+lib/duration/locale.rb
+lib/duration/localizations.rb
+lib/duration/localizations/dutch.rb
+lib/duration/localizations/english.rb
+lib/duration/localizations/french.rb
+lib/duration/localizations/korean.rb
+lib/duration/localizations/polish.rb
+lib/duration/localizations/spanish.rb
+lib/duration/numeric.rb
+lib/duration/time.rb
+lib/duration/time/holidays.rb
+lib/duration/version.rb
+log/debug.log
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake
+test/test_duration.rb
+test/test_helper.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,151 @@
+= Project
+Duration <http://rubyforge.org/projects/duration>
+
+= Author
+Matthew Harris <matt@matthewharris.org>
+http://matthewharris.org
+
+= Synopsis
+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.
+
+As of version 0.1.0, the duration library has been completely rewritten with
+better knowledge.
+
+= Features
+Duration is packed with many features and has plans for many more.
+
+=== Current features
+* Duck typing objects to work with Duration
+* Localization support of formatted strings (feel free to submit your own!)
+* Capability to compare durations to any object (duck typing)
+* Arithmetic operations from Duration instances are legal (duck typing)
+* Convenience methods for creating durations from Time objects
+
+=== Soon to come features
+* Collection of holiday-related methods (creating durations since/until a holiday)
+* A larger collection of locales
+* Definitely have to put more Rubyisms in there too!
+* ...and much more! (can't think of any yet)
+
+= Credits
+I want to thank everyone who downloaded duration, tried it, and sent me e-mails
+of appreciation, feedback, bug reports and suggestions.
+
+Your gratitude has motivated me to rework this almost-dead library and continue
+to maintain it.
+
+Thanks!
+
+= Usage
+Using the duration library is fairly simple and straight-forward.  The base
+class most of you will be using is the Duration class.
+
+=== Initialization
+There are two ways to initialize the Duration class.  One way is to pass an
+object capable of responding to the #to_i method.  That object is expected to
+return an integer or float that represents the number of seconds for the
+duration object.
+
+The second way to initialize the Duration class is to pass a key=>value paired
+Hash object.  The hash's keys will be scanned for units of measurement defiend
+in Duration::UNITS or (the keys of) Duration::MULTIPLES.
+
+Here's an example of using the formerly mentioned solution:
+    duration = Duration.new(Time.now)
+    => #<Duration: 1981 weeks, 3 hours, 50 minutes and 44 seconds>
+    
+As you can see, it gave us the duration since the UNIX epoch.  This works fine
+because Time objects respond to the #to_i method.  And Time#to_i returns a
+UNIX timestamp (which is the number of seconds that have passed since the UNIX
+epoch, January 1, 1970).
+
+Before I move on to demonstrating the second solution, I'd like to note that
+there are Time#to_duration, Time#duration and Duration.since_epoch for
+accomplishing similar tasks.
+
+Alright, the second solution is to pass in a Hash object, as previously
+mentioned.
+
+For example:
+    duration = Duration.new(:hours => 12, :minutes => 58, :days => 14)
+    => #<Duration: 2 weeks, 12 hours and 58 minutes>
+    
+So, it works.  But also notice that I gave it `:days => 14', but it spat out
+`2 weeks'.  Yes, Duration knows what it's doing.
+
+There are more keys you can pass.  Check all the keys available in the
+Duration::MULTIPLES hash to see.  All those keys are valid to pass.  Any
+duplicated multiples will merely be added to each other, so be careful if that's
+not the desired behavior.
+
+=== Formatting
+The Duration class provides Duration#format (alias: Duration#strftime) for
+formatting the time units into a string.
+
+For more information on the identifiers it supports, check out Duration#format.
+
+Here's an example of how to format the known minutes in the duration:
+    duration = Duration.since_epoch
+    duration.format('%~m passed: %m')
+    => "minutes passed: 4"
+    
+Now, this may look a bit tricky at first, but it's somewhat similar to the
+standard strftime() function you see in many lanuages, with the exception of the
+weird "%~m" type identifiers.  These identifiers are the correct terminology for
+the corresponding time unit.
+
+The identifiers are locale-sensitive and can be easily changed to another
+language.  Localization is done internally from the duration library, and does
+not use the system's locales.
+
+If you would like to write a locale for your language (if it doesn't exist),
+you can simply read the source code of the existing locales lying within the
+"duration/localizations" directory.  They are straight-forward 10-15 line
+modules and are not complex at all.
+
+=== Arithmetic
+Duration objects support arithmetic against any object that response to the
+#to_i method.  This is pretty self-explanatory.  What happens when you divide
+a duration by 2?
+
+    duration = Duration.since_epoch
+    => #<Duration: 1981 weeks, 4 hours, 12 minutes and 54 seconds>
+    
+    duration / 2
+    => #<Duration: 990 weeks, 3 days, 14 hours, 6 minutes and 27 seconds>
+    
+Pretty simple, right?
+
+=== Magical Methods
+Finally, Duration has a few magical methods that are handled through the
+#method_missing override.  Duration instances support all method calls to such
+methods as `round_<unit>_to_<unit>' and `<unit>_to_<unit>'.  These methods
+basically convert their <unit> to another <unit> and spit back the numbers.
+
+The `round_<unit>_to_<unit>' method rounds the converted unit.
+
+    Duration.since_epoch.weeks_to_days
+    => 13867.0
+    
+    Duration.since_epoch.round_weeks_to_days
+    => 13867
+    
+    Duration.since_epoch.weeks_to_days.round
+    => 13867
+    
+= Feedback
+Well, I hope you learned a lot from the above explanations.  Time for you to get
+creative on your own now!
+
+If you have any feedback, bug reports, suggestions or locale submissions, just
+e-mail me at matt@matthewharris.org or shugotenshi@gmail.com and I will be glad
+to answer you back.

data/Rakefile

@@ -0,0 +1,4 @@
+require './config/requirements.rb'
+require './config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,73 @@
+require 'duration/version'
+
+AUTHOR = 'Matthew Harris'  # can also be an array of Authors
+EMAIL = "matt@matthewharris.org"
+DESCRIPTION = %[
+  Duration is a library for manipulating timespans.  It can give you readable
+  output for a timespan as well as manipulate the timespan itself.  With this
+  it is possible to make "countdowns" or "time passed since" type objects.
+]
+GEM_NAME = 'blaxter-duration' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'duration' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "kuja"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Duration::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'duration documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README.txt",
+    '--exclude', 'index.txt',
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.spec GEM_NAME do
+  self.author = AUTHOR 
+  self.description = DESCRIPTION
+  self.email = EMAIL
+  self.summary = DESCRIPTION
+  self.url = HOMEPATH
+  self.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  self.test_globs = ["test/**/test_*.rb"]
+  self.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+  self.version = VERS
+
+  # == Optional
+  self.changes = self.paragraphs_of("History.txt", 0..1).join("\n\n")
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'duration'

data/lib/duration.rb

@@ -0,0 +1,216 @@
+require 'duration/version'
+require 'duration/numeric'
+require 'duration/time'
+require 'duration/localizations'
+Duration::Localizations.load_all
+
+# 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
+  include Enumerable
+  
+  # Unit multiples
+  MULTIPLES = {
+    :seconds => 1,
+    :minutes => 60,
+    :hours   => 3600,
+    :days    => 86400,
+    :weeks   => 604800,
+    :second  => 1,
+    :minute  => 60,
+    :hour    => 3600,
+    :day     => 86400,
+    :week    => 604800
+  }
+  
+  # Unit names
+  UNITS = [:seconds, :minutes, :hours, :days, :weeks]
+  
+  attr_reader :total, :seconds, :minutes, :hours, :days, :weeks
+  
+  # Change the locale Duration will use when converting itself to a string
+  def Duration.change_locale(locale)
+    @@locale = Localizations.locales[locale.to_sym] or raise LocaleError, "undefined locale '#{locale}'"
+  end
+  
+  # Load default locale
+  change_locale(Localizations::DEFAULT_LOCALE)
+  
+  # Constructs a Duration instance that represents the duration since the UNIX
+  # epoch (1970-01-01T00:00:00Z)
+  def Duration.since_epoch
+    new(Time.now)
+  end
+  
+  # Calculates the duration "since" a given time.  Assumes that the time is in
+  # the past.  Does not error if the time is in the present or future.
+  def Duration.since(time)
+    new(Time.now.to_i - time.to_i)
+  end
+  
+  # Calculates the duration "until" a given time.  Assumes that the time is in
+  # the future.  Does not error if a time in the present or past is given.
+  def Duration.until(time)
+    new(time.to_i - Time.now.to_i)
+  end
+  
+  # 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)
+    # Two types of arguments are accepted.  If it isn't a hash, it's converted
+    # to an integer.
+    if args.kind_of?(Hash)
+      @seconds = 0
+      MULTIPLES.each do |unit, multiple|
+        unit = unit.to_sym
+        @seconds += args[unit] * multiple if args.key?(unit)
+      end
+    else
+      @seconds = args.to_i
+    end
+    
+    # Calculate duration
+    calculate!
+  end
+  
+  # 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[: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
+		@weeks, @days, @hours, @minutes, @seconds = units
+  end
+  
+  # Compare this duration to another (or objects that respond to #to_i)
+	def <=>(other)
+		@total <=> other.to_i
+	end
+  
+  # Convenient iterator for going through each duration unit from lowest to
+  # highest.  (Goes from seconds...weeks)
+  def each
+    UNITS.each { |unit| yield unit, __send__(unit) }
+  end
+  
+  # Format a duration into a human-readable string.
+  #
+  #   %w  => weeks
+  #   %d  => days
+  #   %h  => hours
+  #   %m  => minutes
+  #   %s  => 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
+  #   
+  def format(format_str)
+    identifiers = {
+      'w'  => @weeks,
+      'd'  => @days,
+      'h'  => @hours,
+      'm'  => @minutes,
+      's'  => @seconds,
+      't'  => @total,
+      'H'  => @hours.to_s.rjust(2, '0'),
+      'M'  => @minutes.to_s.rjust(2, '0'),
+      'S'  => @seconds.to_s.rjust(2, '0'),
+      '~s' => @seconds == 1 ? @@locale.singulars[0] : @@locale.plurals[0],
+      '~m' => @minutes == 1 ? @@locale.singulars[1] : @@locale.plurals[1],
+      '~h' => @hours   == 1 ? @@locale.singulars[2] : @@locale.plurals[2],
+      '~d' => @days    == 1 ? @@locale.singulars[3] : @@locale.plurals[3],
+      '~w' => @weeks   == 1 ? @@locale.singulars[4] : @@locale.plurals[4]
+    }
+
+		format_str.gsub(/%?%(w|d|h|m|s|t|H|M|S|~(?:s|m|h|d|w))/) do |match|
+			match['%%'] ? match : identifiers[match[1..-1]]
+		end.gsub('%%', '%')
+  end
+  
+  def method_missing(m, *args, &block)
+    units = UNITS.join('|')
+    match = /(round_)?(#{units})_to_(#{units})$/.match(m.to_s)
+    if match
+      seconds = ((__send__(match[2].to_sym) * MULTIPLES[match[2].to_sym]) / MULTIPLES[match[3].to_sym].to_f)
+      match[1] ? seconds.round : seconds
+    else
+      super
+    end
+  end
+  
+  # String representation of the Duration object.
+  def to_s
+    @@locale.format.call(self)
+  end
+  
+  # Inspect Duration object.
+	def inspect
+		"#<#{self.class}: #{(s = to_s).empty? ? '...' : s}>"
+	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
+  
+  def seconds=(seconds)
+    initialize :seconds => (@total + seconds) - @seconds
+  end
+  
+  def minutes=(minutes)
+    initialize :seconds => @total - minutes_to_seconds, :minutes => minutes
+  end
+  
+  def hours=(hours)
+    initialize :seconds => @total - hours_to_seconds, :hours => hours
+  end
+  
+  def days=(days)
+    initialize :seconds => @total - days_to_seconds, :days => days
+  end
+  
+  def weeks=(weeks)
+    initialize :seconds => @total - weeks_to_seconds, :weeks => weeks
+  end
+  
+  alias_method :to_i, :total
+  alias_method :strftime, :format
+end