fuzzy_date 0.8.2

data/README

@@ -0,0 +1,57 @@
+  Routines to manage the FuzzyDate Class. There is also an extension to the 
+  ActiveRecord::Base class to provide an 'acts_as_fuzzy_date' class method.
+  
+  Historical dates are often incomplete or approximate and this class allows 
+  such dates to be worked with and stored on a database.
+  
+  construct a new object with FuzzyDate.new( year,month,day,wday,circa)
+     year:   optional..is the year number 0 .. big as you like, -ve for BCE
+     month:  optional.. is month number 1..12, or nil
+     day:    optional.. is day number 1-31 or nil
+     wday:   optional.. day of the week - 0=Sunday .. 6=Saturday
+     circa:  true = daye is approx, or nil/false
+     
+     note that if you supply the weekday and a year/month/day the system will
+     use your weekday as supplied even if this does not actually correspond
+     in reality to the date supplied.
+     
+   construct a new object with FuzzyDate.parse("date_string")
+     date_string = eg: "tuesday"
+                       "12 nov 1012"
+                       "circa 412 bc"
+                       
+   Use in a database table by storing in an integer field of a format large
+   enough to hold the digits of your maximum year + 8. Eg. a BIGNUM field
+   stores 19 useful characters allowing the year to go to 99,999,999,999.
+   ie 99 billion years.
+   
+   Use with an ActiveRecord class ..
+   
+       require 'fuzzy_date'
+
+       class HistoricalPerson < ActiveRecord::Base
+           acts_as_fuzzy_date : birth_date, death_date
+       end
+       
+       
+
+  Copyright (c) Clive Andrews / Reality Bites 2008, 2009, 2010
+
+ 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/lib/fuzzy_date.rb

@@ -0,0 +1,305 @@
+################################################################################
+#
+#  Routines to manage the FuzzyDate Class. There is also an extension to the 
+#  ActiveRecord::Base class to provide an 'acts_as_fuzzy_date' class method.
+#--
+#  Copyright (c) Clive Andrews / Reality Bites 2008, 2009, 2010
+#
+# 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.
+#
+# version 20100224-1
+# ++
+#  
+################################################################################
+require 'date'
+
+
+# A fuzzy date is a representation of a date which may well be incomplete
+# or imprecise. You can enter the exact date or for example just the day of
+# the week or the year or a combination thereof. One can also add the Circa
+# prefix to any date. The FuzzyDate object is immutable so if you wish to 
+# change a FuzzyDate value it is neccessary to create a new FuzzyDate.
+class FuzzyDate
+  
+  include Comparable
+  
+  # overload the Date class to modify its parsing routine a little
+  #
+  class FDate < Date # :nodoc:
+    def self._parse_year(str, e) 
+      if str.sub!(/(\d{3,})\b/in, ' ')
+        e.year = $1.to_i
+        true
+      else
+        super(str,e)
+      end
+    end
+  end # FDate
+  
+  # create a new FuzzyDate object. There are no checks here to 
+  # validate if the date is valid or not.. eg there is no check 
+  # that the day of the week actually corresponds to the actual
+  # date if completely specified.
+  def initialize(year=nil,month=nil,day=nil,wday=nil,circa=nil)
+    raise "FuzzyDate: invalid month"   if month && ((month>12) || (month<1))
+    raise "FuzzyDate: invalid day"     if day   && ((day>31)   || (day<1))
+    raise "FuzzyDate: invalid weekday" if wday  && ((wday>6)   || (wday<0))
+    raise "FuzzyDate: year too big !"  if year  && (year.abs > 99999999999 )
+    @year  = year && year.abs
+    @month = month
+    @day   = day
+    @wday  = wday
+    @circa = circa
+    @bce   = year && (year.to_i < 0)
+  end
+  
+  # returns an integer representing the day of the week, 0..6
+  # with Sunday=0. returns nil if not known. 
+  def wday 
+    if !@wday && complete? && (@year > 0)
+      to_date.wday
+    else
+      @wday
+    end
+  end
+  
+  # returns the day of the month ( 1..n ). returns nil if not known.
+  def day
+    @day
+  end
+  
+  # returns the month number (1..12). returns nil if not known.
+  def month
+    @month
+  end
+  
+  # returns the year number (including century)
+  def year
+    @year
+  end
+  
+  # is the date approximate ?
+  def circa?
+    @circa
+  end
+  
+  # is the date before the year zero.
+  def bce?
+    @bce
+  end
+  
+  #  return an integer representing only the month and day
+  def birthday
+    month * 100 + day if month && day
+  end
+  
+  # is the date complete
+  def complete?
+    year && (month  && month < 13) && (day  && day < 32)
+  end
+  
+  # is the date completely unknown
+  def unknown?
+    !@year && !@month && !@day && !@wday
+  end
+  
+  # convert to integer format
+  def to_i
+    to_db
+  end
+  
+  # convert the fuzzy date into a format which can be stored in a database. The
+  # storage format is integer format (BIGINT) with digits having the following positional
+  # significance:
+  #
+  #   (-/+)  (YYYYYYYYYYY.....Y)MMDDd[01][01]
+  #
+  #   where + is AD or CE
+  #         - is BC or BCE
+  #         1 at end = circa or C otherwise 0
+  #         1 at 2nd from end  = year unknown - otherwise missing year = year 0
+  #         YYYYY is the year number 0 or missing  = year absent OR value is unknown
+  #         MM    is the month number or 13 for unknown
+  #         DD    is the day of the month or 32 for unknown
+  #         d     is the day of the week where 8 = unknown, 1=Sunday .. 7=Saturday
+  #
+  #
+  #   this wierd format has been chosen to allow sorting within the database and to
+  #   avoid leading zeros containing information from being stripped from the representation.
+  #
+  #   save in a  mysql database in format BIGINT 
+  #
+  def to_db
+    str = ''
+    str= str + (@year > 0 ? @year.to_s : '') if @year
+    str= str + (@month ? "%02d" % @month.to_s : '13')
+    str= str + (@day ? "%02d" % @day.to_s : '32')
+    str= str + (@wday ? (@wday+1).to_s : '8')
+    str= str + (@year  ? '0' : '1')
+    str= str + (@circa  ? '1' : '0')
+    i = str.to_i
+    i = -i if @bce
+    i
+  end
+  
+  # create a new FuzzyDate object from the database formatted
+  # integer.
+  def self.new_from_db(i)
+    return nil unless i
+    str = i.to_s
+    return nil if str == '0'
+    bce = false
+    raise "Invalid Fuzzy Time String - #{str}" unless str =~/^[+-]?\d{6,}$/
+    str.sub!(/^-/){|m| bce= true;""} 
+    str = ("000000" + str)[-7,7] if str.length < 7
+    circa   =  (str[-1,1] == '1')
+    year    =  (str[-2,1] == '1' ? nil : 0)
+    wday    = str[-3,1].to_i - 1
+    day     = str[-5,2].to_i
+    month   = str[-7,2].to_i
+    wday    = nil if ((wday<0) || (wday>6))
+    day     = nil if ((day==0) || (day>31))
+    month   = nil if ((month==0) || (month > 12))
+    year    = (str[0..-8].to_i > 0 ? str[0..-8].to_i : year )
+    year = -year if year && bce
+    new(year,month,day,wday,circa)
+  end
+  
+  # convert to a human readable string
+  def to_s
+    if unknown?
+      str = "unknown"
+    else
+      str = ""
+      str = "circa "                        if circa?
+      str+= FDate::DAYNAMES[wday]    + " "  if wday 
+      str+= day.to_s + " "                  if day 
+      str+= FDate::MONTHNAMES[month] + " "  if month
+      str+= year.to_s                       if year 
+      str += " bce"                         if bce?
+      str.strip
+    end
+  end
+  
+  # if the date is complete then return a regular
+  # Date object
+  def to_date
+    return nil unless complete?
+    Date.new(@year,@month,@day)
+  end
+  
+  # create a FuzzyDate object from a Date object
+  def self.new_from_date( date)
+    new(date.year,date.month,date.day)
+  end
+  
+  # create a new date object by parsing a string
+  def self.parse( str )
+    
+    return unless str && str.length > 0
+    
+    continue = true
+    circa    = false
+    bce      = false
+    unknown  = false
+    
+    #filter out 'c' or 'circa'
+    str.sub!(/CIRCA/i){|m| circa=true;continue=nil} if continue
+    str.sub!(/^CA /i){|m| circa=true;continue=nil} if continue
+    str.sub!(/^C /i){|m| circa=true;continue=nil} if continue
+    str.sub!(/ABOUT/i){|m| circa=true;continue=nil} if continue
+    str.sub!(/AROUND/i){|m| circa=true;continue=nil} if continue
+    str.sub!(/ROUND/i){|m| circa=true;continue=nil} if continue
+    str.sub!(/APPROX/i){|m| circa=true;continue=nil} if continue
+    str.sub!(/APPROXIMATELY/i){|m| circa=true;continue=nil} if continue
+    
+    #filter out 'bc' 'bce'
+    continue = true
+    str.sub!(/BCE/i){|m| bce=true;continue=nil}
+    str.sub!(/BC/i){|m| bce=true;continue=nil} if continue
+    
+    #filter out 'unknown'
+    continue = true
+    str.sub!(/UNKNOWN/i){|m| unknown=true;continue=nil}
+    
+    # if date is unknown then return an empty FuzzyDate
+    return self.new if unknown
+    
+    # now try to parse the remaining string with the Date parse
+    # method.
+    
+    components= FDate._parse(str,false)
+    year  = components[:year]
+    month = components[:mon]
+    day   = components[:mday]
+    wday  = components[:wday]
+    
+    # fudge the results a bit
+    year,day = day,nil if (day && !month && !year) || (!year && (day.to_i > 31))
+    if year && year < 0 
+      year = year.abs
+      bce  = true
+    end
+    
+    year = -year if bce
+    self.new(year,month,day,wday,circa)
+  end
+  
+  def <=>(other) self.to_db <=> other.to_db end
+  
+end #class FuzzyDate
+
+# add an acts_as_fuzzy_date helper to ActiveRecord to define
+# a table field as a FuzzyDate.
+#
+# eg:
+#
+#       require 'fuzzy_date'
+#
+#       class HistoricalPerson < ActiveRecord::Base
+#           acts_as_fuzzy_date : birth_date, death_date
+#       end
+#
+if defined? ActiveRecord::Base
+  class ActiveRecord::Base
+    class << self
+      def acts_as_fuzzy_date(*args)
+        args.each do |name|
+          str =<<-EOF
+          def #{name}
+             FuzzyDate.new_from_db(self['#{name}'])
+          end
+    
+          def #{name}=(s)
+             if s.kind_of? String
+                 self['#{name}'] = FuzzyDate.parse(s).to_db unless s.strip.empty?
+             elsif s.kind_of? FuzzyDate
+                 self['#{name}']=s.to_db
+             elsif !s
+                 self['#{name}'] = nil
+             end
+          end
+EOF
+          class_eval str
+        end
+      end
+    end
+  end
+end

data/test/test_fuzzy_date.rb

@@ -0,0 +1,122 @@
+$:.unshift File.join(File.dirname(__FILE__),"..","lib")
+
+require "test/unit"
+require 'fuzzy_date'
+
+class TestItem < Test::Unit::TestCase
+  def test_basic_parse
+    # complete date
+    assert_not_nil(FuzzyDate.new)
+    d1 = FuzzyDate.parse("Thurs 31 december 1998" )
+    assert_equal(31, d1.day )
+    assert_equal(12, d1.month )
+    assert_equal(1998,d1.year)
+    assert_equal(4, d1.wday )
+    assert ( ! d1.bce?)
+    assert ( ! d1.circa?)
+    assert ( d1.complete?)
+    assert ( !d1.unknown?)
+    # empty
+    d1 = FuzzyDate.parse("" )
+    assert_nil( d1.day )
+    assert_nil( d1.month )
+    assert_nil(d1.year)
+    assert ( ! d1.circa?)
+    assert_equal(nil, d1.wday )
+    assert ( ! d1.bce?)
+    assert ( !d1.complete?)
+    assert ( d1.unknown?)
+    # just year
+    d1 = FuzzyDate.parse("1540" )
+    assert_nil( d1.day )
+    assert_nil( d1.month )
+    assert_equal(1540,d1.year)
+    assert_equal(nil, d1.wday )
+    assert ( ! d1.bce?)
+    assert ( !d1.complete?)
+    assert ( ! d1.circa?)
+    assert ( !d1.unknown?)
+    # just month
+    d1 = FuzzyDate.parse("september" )
+    assert_nil( d1.day )
+    assert_equal(9, d1.month )
+    assert_nil(d1.year)
+    assert_equal(nil, d1.wday )
+    assert ( ! d1.bce?)
+    assert ( !d1.complete?)
+    assert ( ! d1.circa?)
+    assert ( !d1.unknown?)
+    # just weekday
+    d1 = FuzzyDate.parse("tuesday" )
+    assert_equal(nil, d1.day )
+    assert_equal(2, d1.wday )
+    assert_nil( d1.month )
+    assert_nil(d1.year)
+    assert ( ! d1.bce?)
+    assert ( !d1.complete?)
+    assert ( ! d1.circa?)
+    assert ( !d1.unknown?)
+    # circa
+    d1 = FuzzyDate.parse("c sunday 1066" )
+    assert_equal(nil, d1.day )
+    assert_equal(0, d1.wday )
+    assert_nil( d1.month )
+    assert_equal(1066,d1.year)
+    assert ( ! d1.bce?)
+    assert ( !d1.complete?)
+    assert ( d1.circa?)
+    assert ( !d1.unknown?)
+    # bce
+    d1 = FuzzyDate.parse(" 23 march 366 bc" )
+    assert_equal(23, d1.day )
+    assert_equal(nil, d1.wday )
+    assert_equal(3, d1.month )
+    assert_equal(366,d1.year)
+    assert ( d1.bce?)
+    assert ( d1.complete?)
+    assert ( !d1.circa?)
+    assert ( !d1.unknown?)
+  end
+  
+  def test_database
+    10000.times do 
+      d = make_fuzzy_date
+      puts d.to_s
+      i = d.to_i
+      i = i * 1 # reformat ?
+      d2 = FuzzyDate.new_from_db( i )
+      assert_equal( d.to_i, d2.to_i)
+    end
+  end
+  
+  def test_compare
+    assert( FuzzyDate.parse("23 april 2000") == FuzzyDate.parse("23 april 2000") )
+    assert( FuzzyDate.parse("24 april 2000") > FuzzyDate.parse("23 april 2000") )
+    assert( FuzzyDate.parse("april 2000") > FuzzyDate.parse("march 2000") )
+    assert( FuzzyDate.parse("jan 2001") > FuzzyDate.parse("dec 2000") )
+    assert( FuzzyDate.parse("sept") > FuzzyDate.parse("july") )
+  end
+  
+  # generate a random fuzzy date
+  def make_fuzzy_date
+    #    1  2  3  4  5  6  7  8  9  10 11 12
+    tab=[31,28,31,30,31,30,31,31,30,31,30,31]
+    year      = rand(2000)
+    month     = rand(12) + 1
+    wday      = rand(7)
+    day       = rand(tab[month-1]) + 1
+    circa     = rand(4) == 0
+    bce       = rand(2) == 0
+    do_year   = rand(3) > 0
+    do_month  = rand(3) > 0
+    do_day    = rand(3) > 0
+    do_wday   = rand(3) > 0
+    
+    year = - year if bce
+    FuzzyDate.new( do_year && year,
+                   do_month && month,
+                   do_day && day,
+                   do_wday && wday,
+                   circa)
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification 
+name: fuzzy_date
+version: !ruby/object:Gem::Version 
+  version: 0.8.2
+platform: ruby
+authors: 
+- Clive Andrews
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-23 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: FuzzyDate is a Ruby class for working with incomplete dates.
+email: pacman@realitybites.eu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- lib/fuzzy_date.rb
+has_rdoc: true
+homepage: http://www.realitybites.eu
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: fuzzy_date
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: FuzzyDate is a Ruby class for working with incomplete dates.Can be used in Combination with ActiveRecord.
+test_files: 
+- test/test_fuzzy_date.rb