kronos 0.1.1 → 0.1.2

data/README.md

@@ -1,30 +1,74 @@
-# README
+# Kronos
 
-Kronos provides flexible date parsing. Currently, it is just a thin wrapper over [ParseDate](http://ruby-doc.org/stdlib/libdoc/parsedate/rdoc/index.html). Here is how it works:
+Kronos is a library for Ruby that provides flexible date-related parsing. 
+
+## Introduction
+
+The approach of Kronos is simple: parse what you can and don't be more specific than is justified. In other words, don't attempt to force the rest into a Date object. It can handle a date, just a month and day, or just a year. Some examples:
 
     c = Kronos.parse("1991")
-    c.year
-    # => 1991
-    # these work too: "91" and "'91"
+    c.year  # => 1991
+    c.month # => nil
+    c.day   # => nil
 
+    # These give the same results:
+    c = Kronos.parse("91")
+    c = Kronos.parse("'91")
+    
     Kronos.parse("1/17/2007")
-    c.year
-    # => 2007
-
+    c.year  # => 2007
+    c.month # => 1
+    c.day   # => 17
+    
     Kronos.parse("January 1976")
-    c.year
-    # => 1976
+    c.year  # => 1976
+    c.month # => 1
+    c.day   # => nil
+
+## Comparison with other libraries
+
+In contrast, other date parsing libraries, such as [Chronic](http://github.com/mojombo/chronic) or [ParseDate](http://ruby-doc.org/stdlib/libdoc/parsedate/rdoc/index.html), try to parse a string into a full Date object, which requires a year, month, and day. Even if a month or day is not specified, they are going to pick one for you. For example:
+
+    require 'parsedate'
+    require 'chronic'
+
+    Chronic.parse("Aug-96")
+    # => Fri Aug 16 12:00:00 -0400 1996
+    # The day (16) is arbitrarily chosen
+    
+    ParseDate.parsedate("Aug-96")
+    # => [nil, 8, 96, nil, nil, nil, nil, nil]
+    # The year (nil) is wrong
+    # The day (96) is arbitrarily chosen and out of range
+    
+    Chronic.parse("1991")
+    # => Fri Dec 11 20:31:00 -0500 2009
+    # The year is wrong (2009)
+    # The month (12) and day (11) are arbitrarily chosen
+    
+    ParseDate.parsedate("1991")
+    # => [nil, 19, 91, nil, nil, nil, nil, nil]
+    # The year is wrong (nil)
+    # The month (19) and day (91) are arbitrarily chosen and out of range
+
+## Implementation
+
+Kronos is currently implemented as a thin wrapper over [ParseDate](http://ruby-doc.org/stdlib/libdoc/parsedate/rdoc/index.html).
+
+## Future Plans
+
+In the future, I would like Kronos to be able to handle date-related comparisons properly.
 
-At present, neither [Chronic](http://github.com/mojombo/chronic) nor ParseDate parses a plain year (e.g. "1991") correctly.
+The Ruby date libraries that I have seen make the assumption that you are specifying a point (i.e. a particular date), not an interval (such as an entire month or year). Comparing intervals adds a little bit of complexity. For example:
 
-In the future, I would like Kronos to be able to handle comparisons properly. Most Ruby date libraries seem to have the assumption that you are specifying a point, not an interval. Comparing intervals adds a little bit of complexity. For example:
+    year = Kronos.parse("1974")
+    month = Kronos.parse("March 1974")
+    year < month    # => false
+    year > month    # => false
+    month == year   # => false
+    year.in?(month) # => false
+    month.in?(year) # => true
 
-    c1 = Kronos.parse("1974")
-    c2 = Kronos.parse("March 1974")
-    c1 < c2 # => false
-    c1 > c2 # => false
-    c1 == c2 # => false
-    c1.in?(c2) # => false
-    c2.in?(c1) # => true
+## Feedback
 
-I have not yet seen Ruby date libraries that behave in this way.
+I would appreciate your feedback. Thanks! (David James, Sunlight Labs, Washington, DC)

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/kronos.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{kronos}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["David James"]
-  s.date = %q{2009-12-02}
+  s.date = %q{2009-12-11}
   s.description = %q{Kronos provides flexible date parsing. Currently just a thin layer on top of ParseDate.}
   s.email = %q{djames@sunlightfoundation.com}
   s.extra_rdoc_files = [

data/lib/kronos.rb

@@ -8,13 +8,20 @@ class Kronos
     if string =~ /^\d{4}$/
       self.year = string.to_i
     elsif string =~ /^[']?(\d{2})$/
-      n = $1.to_i
-      self.year = n >= 70 ? 1900 + n : 2000 + n
+      self.year = to_full_year($1.to_i)
     else
       values = ParseDate.parsedate(string)
-      self.year  = values[0]
-      self.month = values[1]
-      self.day   = values[2]
+      if values[0]
+        # ParseDate parsed a year
+        self.year  = to_full_year(values[0])
+        self.month = values[1]
+        self.day   = values[2]
+      elsif values[2]
+        # ParseDate parsed a day but not a year
+        self.year  = to_full_year(values[2])
+        self.month = values[1]
+        self.day   = nil
+      end
     end
     self
   end
@@ -31,4 +38,14 @@ class Kronos
     self.new.parse(string)
   end
   
+  protected
+  
+  def to_full_year(x)
+    case x
+    when (0 .. 69)  then 2000 + x
+    when (70 .. 99) then 1900 + x
+    else x
+    end
+  end
+  
 end

data/spec/kronos_spec.rb

@@ -97,6 +97,29 @@ describe "Kronos" do
     }
   end
   
+  it "Aug-96" do
+    c = Kronos.parse("Aug-96")
+    c.year.should  == 1996
+    c.month.should == 8
+    c.day.should   == nil
+    c.to_hash.should == {
+      'year'  => 1996,
+      'month' => 8,
+    }
+  end
+
+  it "15-Mar-96" do
+    c = Kronos.parse("15-Mar-96")
+    c.year.should  == 1996
+    c.month.should == 3
+    c.day.should   == 15
+    c.to_hash.should == {
+      'year'  => 1996,
+      'month' => 3,
+      'day'   => 15,
+    }
+  end
+  
   it "empty string" do
     c = Kronos.parse("")
     c.year.should  == nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: kronos
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - David James
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-02 00:00:00 -05:00
+date: 2009-12-11 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency