edtf 0.0.6 → 0.0.7

data/features/step_definitions/edtf_steps.rb

@@ -12,7 +12,7 @@ Then /^the EDTF String should be "([^"]*)"$/i do |edtf|
 end
 
 When /^I parse the string "([^"]*)"$/ do |string|
-  @date = EDTF.parse(string)
+  @date = EDTF.parse!(string)
 end
 
 Then /^the year should be "([^"]*)"$/ do |year|
@@ -72,6 +72,10 @@ Then /^the interval should include the date "([^"]*)"$/ do |date|
   @date.should include(Date.parse(date))
 end
 
+Then /^the interval should cover the date "([^"]*)"$/ do |date|
+  @date.should cover(Date.parse(date))
+end
+
 
 Then /^the date should be uncertain\? "([^"]*)"$/ do |arg1|
   @date.uncertain?.should == !!(arg1 =~ /y(es)?/i)
@@ -109,3 +113,33 @@ end
 Then /^the unspecified string code be "([^"]*)"$/ do |arg1|
   @date.unspecified.to_s.should == arg1
 end
+
+When /^I parse the following strings an error should be raised:$/ do |table|
+	table.raw.each do |row|
+		expect { Date.edtf!(row[0]) }.to raise_error(ArgumentError)
+	end
+end
+
+When /^the year is uncertain: "([^"]*)"$/ do |arg1|
+	@date.uncertain!(:year) if arg1 =~ /y(es)?/i
+end
+
+When /^the month is uncertain: "([^"]*)"$/ do |arg1|
+	@date.uncertain!(:month) if arg1 =~ /y(es)?/i
+end
+
+When /^the day is uncertain: "([^"]*)"$/ do |arg1|
+	@date.uncertain!(:day) if arg1 =~ /y(es)?/i
+end
+
+When /^the year is approximate: "([^"]*)"$/ do |arg1|
+	@date.approximate!(:year) if arg1 =~ /y(es)?/i
+end
+
+When /^the month is approximate: "([^"]*)"$/ do |arg1|
+	@date.approximate!(:month) if arg1 =~ /y(es)?/i
+end
+
+When /^the day is approximate "([^"]*)"$/ do |arg1|
+	@date.approximate!(:day) if arg1 =~ /y(es)?/i
+end

data/lib/edtf.rb

@@ -28,18 +28,23 @@
 # policies, either expressed or implied, of the copyright holder.
 #++
 
+if ENV['DEBUG']
+  require 'ruby-debug'
+  Debugger.start
+end
+
 require 'date'
 require 'time'
 
 autoload :Rational, 'rational'
 
 require 'forwardable'
+require 'enumerator'
 
 require 'active_support/core_ext/date/calculations'
 require 'active_support/core_ext/date_time/calculations'
 require 'active_support/core_ext/time/calculations'
 
-
 require 'active_support/core_ext/date/conversions'
 
 require 'edtf/compatibility'
@@ -63,11 +68,17 @@ require 'edtf/extensions'
 # To parse EDTF strings use either `Date.edtf` of `EDTF.parse`.
 #
 module EDTF
-  
+
+  module_function
+
   def parse(input, options = {})
-    ::Date.edtf(input, options)
+    parse!(input, options)
+  rescue
+    nil
   end
   
-  module_function :parse
-  
+  def parse!(input, options = {})
+    ::Date.edtf!(input, options)
+  end
+    
 end

data/lib/edtf/compatibility.rb

@@ -1,19 +1,8 @@
 
-# unless DateTime.respond_to?(:to_time)
-#   require 'time'
-#   
-#   class DateTime
-#     def to_time
-#       Time.parse(to_s)
-#     end
-#   end  
-# end
-
-	
 class DateTime
-	
-	def iso8601
-		to_time.iso8601
-	end unless method_defined?(:iso8601)
-	
+
+  def iso8601
+    to_time.iso8601
+  end unless method_defined?(:iso8601)
+
 end

data/lib/edtf/date.rb

@@ -1,34 +1,66 @@
 class Date
   
-  PRECISIONS = [:year, :month, :day].freeze
+  PRECISION = [:year, :month, :day].freeze
+  PRECISIONS = Hash[*PRECISION.map { |p| [p, "#{p}s".to_sym] }.flatten].freeze
+  
 	FORMATS = %w{ %04d %02d %02d }.freeze
 
+	SYMBOLS = {
+		:uncertain   => '?',
+		:approximate => '~',
+		:calendar    => '^',
+		:unspecified => 'u'
+	}.freeze
+		
   EXTENDED_ATTRIBUTES = %w{ calendar precision uncertain approximate
     unspecified }.map(&:to_sym).freeze
    	
   extend Forwardable  
   
   class << self
+    
     def edtf(input, options = {})
-      ::EDTF::Parser.new(options).parse(input)
+      edtf!(input, options)
+    rescue
+      nil
+    end
+    
+    def edtf!(input, options = {})
+      ::EDTF::Parser.new(options).parse!(input)
     end
   end
   
   attr_accessor :calendar
   
-  PRECISIONS.each do |p|
-    define_method("#{p}_precision?") { @precision == p }
-    define_method("#{p}_precision!") { @precision =  p }
+  PRECISION.each do |p|
+    define_method("#{p}_precision?") { precision == p }
+    
+    define_method("#{p}_precision!") do
+      self.precision = p
+      self
+    end
+    
+    define_method("#{p}_precision") do
+      change(:precision => p)
+    end
   end
   
-  def dup
-    d = super
-    d.uncertain = uncertain.dup
-    d.approximate = approximate.dup
-    d.unspecified = unspecified.dup
-    d
+  
+  def initialize_copy(other)
+		super
+		copy_extended_attributes(other)
   end
   
+  
+  # Alias advance method from Active Support.
+  alias original_advance advance
+
+  # Provides precise Date calculations for years, months, and days.  The +options+ parameter takes a hash with
+  # any of these keys: <tt>:years</tt>, <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>.
+  def advance(options)
+    original_advance(options).copy_extended_attributes(self)
+  end
+
   # Alias change method from Active Support.
   alias original_change change
   
@@ -41,6 +73,7 @@ class Date
     d
   end
   
+  
   # Returns this Date's precision.
   def precision
     @precision ||= :day
@@ -49,21 +82,17 @@ class Date
 	# Sets this Date/Time's precision to the passed-in value.
   def precision=(precision)
     precision = precision.to_sym
-    raise ArgumentError, "invalid precision #{precision.inspect}" unless PRECISIONS.include?(precision)
+    raise ArgumentError, "invalid precision #{precision.inspect}" unless PRECISION.include?(precision)
     @precision = precision
     update_precision_filter[-1]
   end
   
-  def self.included(base)
-    base.extend(ClassMethods)
-  end
-  
   def uncertain
     @uncertain ||= EDTF::Uncertainty.new
   end
 
   def approximate
-    @approximate ||= EDTF::Uncertainty.new
+    @approximate ||= EDTF::Uncertainty.new(nil, nil, nil, 8)
   end
 
   def unspecified
@@ -108,7 +137,7 @@ class Date
 
   alias precisely! precise!
   
-  def_delegators :unspecified, :unspecified?, :specified?, :unsepcific?, :specific?
+  def_delegators :unspecified, :unspecified?, :specified?, :unspecific?, :specific?
   
   def unspecified!(arguments = precision_filter)
     unspecified.unspecified!(arguments)
@@ -124,35 +153,103 @@ class Date
 
   alias specific! specified!
   
+  # Returns false for Dates.
   def season?; false; end
   
+  # Returns true if the Date has an EDTF calendar string attached.
+	def calendar?; !!@calendar; end
+
+  # Converts the Date into a season.
   def season
     Season.new(self)
   end
   
+  # Returns the Date's EDTF string.
   def edtf
-    FORMATS.take(values.length).join('-') % values << (uncertain? ? '?' : '')
+		return "y#{year}" if long_year?
+		
+		s = FORMATS.take(values.length).zip(values).map { |f,v| f % v }
+		s = unspecified.mask(s)
+
+    unless (h = ua_hash).zero?
+      #
+      # To efficiently calculate the uncertain/approximate state we use
+      # the bitmask. The primary flags are:
+      #
+      # Uncertain:    1 - year,  2 - month,  4 - day
+      # Approximate:  8 - year, 16 - month, 32 - day
+      #
+      # Invariant: assumes that uncertain/approximate are not set for values
+      # not covered by precision!
+      #
+      y, m, d = s
+      
+      # ?/~ if true-false or true-true and other false-true
+      y << SYMBOLS[:uncertain]   if  3&h==1 || 27&h==19
+      y << SYMBOLS[:approximate] if 24&h==8 || 27&h==26
+      
+
+      # combine if false-true-true and other m == d 
+      if 7&h==6 && (48&h==48 || 48&h==0)  || 56&h==48 && (6&h==6 || 6&h==0)
+        m[0,0] = '('
+        d << ')'
+      else
+        case
+        # false-true
+        when 3&h==2 || 24&h==16
+          m[0,0] = '('
+          m << ')'
+      
+        # *-false-true
+        when 6&h==4 || 48&h==32
+          d[0,0] = '('
+          d << ')'
+        end
+      
+        # ?/~ if *-true-false or *-true-true and other m != d 
+        m << SYMBOLS[:uncertain]   if h!=31 && (6&h==2  ||  6&h==6  && (48&h==16 || 48&h==32))
+        m << SYMBOLS[:approximate] if h!=59 && (48&h==16 || 48&h==48 && (6&h==2 || 6&h==4))
+      end
+      
+      # ?/~ if *-*-true
+      d << SYMBOLS[:uncertain]   if  4&h==4
+      d << SYMBOLS[:approximate] if 32&h==32      
+    end
+
+    s = s.join('-')
+		s << SYMBOLS[:calendar] << calendar if calendar?
+		s
   end
 
 	alias to_edtf edtf
 	
-	# Returns a the Date of the next day, month, or year depending on the
+	# Returns the Date of the next day, month, or year depending on the
 	# current Date/Time's precision.
-  def next
-    send("next_#{precision}")
+  def next(n = 1)
+    if n > 1
+      1.upto(n).map { |by| advance(PRECISIONS[precision] => by) }
+    else
+      advance(PRECISIONS[precision] => 1)
+    end
   end
-  
-  # def succ
-  # end
 
-  # def ==(other)
-  # end
+  alias succ next
 
-  # def <=>(other)
-  # end
+	# Returns the Date of the previous day, month, or year depending on the
+	# current Date/Time's precision.
+  def prev(n = 1)
+    if n > 1
+      1.upto(n).map { |by| advance(PRECISIONS[precision] => -by) }
+    else
+      advance(PRECISIONS[precision] => -1)
+    end
+  end
+  
+  def <=>(other)
+		return nil unless other.is_a?(::Date)
+		values <=> other.values
+  end
 
-  # def ===(other)
-  # end
   
 	# Returns an array of the current year, month, and day values filtered by
 	# the Date/Time's precision.
@@ -160,16 +257,24 @@ class Date
     precision_filter.map { |p| send(p) }
   end
   
-  # Returns the same date with negated year        
+  # Returns the same date but with negated year.
   def negate
 		change(:year => year * -1)
   end
   
   alias -@ negate
   
-  
+	# Returns true if this Date/Time has year precision and the year exceeds four digits.
+	def long_year?
+		precision == :year && year.abs > 9999
+	end
+	
   private
-
+	
+	def ua_hash
+	  uncertain.hash + approximate.hash
+	end
+	
   def precision_filter
     @precision_filter ||= update_precision_filter
   end
@@ -188,5 +293,16 @@ class Date
   protected
   
   attr_writer :uncertain, :unspecified, :approximate
-  
+
+  def copy_extended_attributes(other)
+    @uncertain   = other.uncertain.dup
+    @approximate = other.approximate.dup
+    @unspecified = other.unspecified.dup
+
+    @calendar    = other.calendar.dup if other.calendar?
+    @precision   = other.precision
+
+    self
+  end  
+
 end

data/lib/edtf/date_time.rb

@@ -1,9 +1,9 @@
 class DateTime
-	
-	alias edtf iso8601
-	alias to_edtf edtf
-	
+
+  alias edtf iso8601
+  alias to_edtf edtf
+
   def values
-    super + [hour,minute,second,offset]
+    super().cocat([hour,minute,second,offset])
   end
 end

data/lib/edtf/interval.rb

@@ -1,86 +1,285 @@
 module EDTF
   
+  # An interval behaves like a regular Range but is dedicated to EDTF dates.
+  # Most importantly, intervals use the date's precision when generating
+  # the set of contained values and for membership tests. All tests are
+  # implemented without iteration and should therefore be considerably faster
+  # than if you were to use a regular Range.
+  #
+  # For example, the interval "2003/2006" covers the years 2003, 2004, 2005
+  # and 2006. Converting the interval to an array would result in a an array
+  # containing exactly four dates with year precision. This is also reflected
+  # in membership tests.
+  #
+  #     Date.edtf('2003/2006').length                           -> 4
+  #
+  #     Date.edtf('2003/2006').include? Date.edtf('2004')       -> true
+  #     Date.edtf('2003/2006').include? Date.edtf('2004-03')    -> false
+  #
+  #     Date.edtf('2003/2006').cover? Date.edtf('2004-03')      -> true
+  #
   class Interval
 
     extend Forwardable
-
-    include Enumerable
     
-    def_delegators :to_range, *(Range.instance_methods - Enumerable.instance_methods - Object.instance_methods)
+    include Comparable
+    include Enumerable
 
-    attr_reader :from, :to
+    # Intervals delegate hash calculation to Ruby Range
+    def_delegators :to_range, :eql?, :hash
+    def_delegators :to_a, :length, :empty?
     
-    def initialize(from = :open, to = :open)
+    attr_accessor :from, :to
+
+    def initialize(from = Date.today, to = :open)
       @from, @to = from, to
     end
     
-    def from=(from)
-      @from = from || :open
-    end
-
-    def to=(to)
-      @to = to || :open
-    end
-
     [:open, :unknown].each do |method_name|
-      
-      define_method("#{method_name}?") do
-        @to == method_name || @from == method_name
-      end
-
-      define_method("#{method_name}!") do
+      define_method("#{method_name}_end!") do
         @to = method_name
+        self
       end
 
-      alias_method("#{method_name}_end!", "#{method_name}!")
-      
       define_method("#{method_name}_end?") do
         @to == method_name
       end
-      
     end
-
+    
+    alias open! open_end!
+    alias open? open_end?
+    
     def unknown_start?
-      @from == :unknown
+      from == :unknown
     end
     
     def unknown_start!
       @from = :unknown
+      self
+    end
+    
+    def unknown?
+      unknown_start? || unknown_end?
+    end
+    
+    # Returns the intervals precision. Mixed precisions are currently not
+    # supported; in that case, the start date's precision takes precedence.
+    def precision
+      min.precision || max.precision
+    end
+    
+    # Returns true if the precisions of start and end date are not the same.
+    def mixed_precision?
+      min.precsion != max.precision
     end
     
+    def each(&block)
+      step(1, &block)
+    end
+
+
+    # call-seq:
+    #     interval.step(by=1) { |date| block }  -> self
+    #     interval.step(by=1)                   -> Enumerator
+    #
+    # Iterates over the interval by passing by elements at each step and
+    # yielding each date to the passed-in block. Note that the semantics
+    # of by are precision dependent: e.g., a value of 2 can mean 2 days,
+    # 2 months, or 2 years.
+    #
+    # If not block is given, returns an enumerator instead.
+    #
+    def step(by = 1)
+      raise ArgumentError unless by.respond_to?(:to_i) 
+      
+      if block_given?
+        f, t, by = min, max, by.to_i
+
+        unless f.nil? || t.nil? || by < 1
+          by = { Date::PRECISIONS[precision] => by }
+          
+          until f > t do
+            yield f
+            f = f.advance(by)
+          end
+        end
+        
+        self
+      else
+        enum_for(:step, by)
+      end
+    end
+
+    
+    # This method always returns false for Range compatibility. EDTF intervals
+    # always include the last date.
+    def exclude_end?
+      false
+    end
+    
+    
     # TODO how to handle +/- Infinity for Dates?
+    # TODO we can't delegate to Ruby range for mixed precision intervals
     
+    # Returns the Interval as a Range.
     def to_range
       case
-      when open?
-        nil
-      when unknown_end?
+      when open?, unknown?
         nil
       else
-        Range.new(unknown_start? ? Date.new : @from, bounds)
+        Range.new(unknown_start? ? Date.new : @from, max)
       end
     end
     
-    def bounds
+    # Returns true if other is an element of the Interval, false otherwise.
+    # Comparision is done according to the Interval's min/max date and
+    # precision.
+    def include?(other)
+      cover?(other) && precision == other.precision
+    end
+    alias member? include?
+    
+    # Returns true if other is an element of the Interval, false otherwise.
+    # In contrast to #include? and #member? this method does not take into
+    # account the date's precision.    
+    def cover?(other)
+      return false unless other.is_a?(Date)
+      
+      other = other.day_precision
+      
       case
-      when open_end?, to.day_precision? 
-        to
-      when to.month_precision?
-        to.end_of_month
+      when unknown_start?
+        max.day_precision! == other
+      when unknown_end?
+        min.day_precision! == other
+      when open_end?
+        min.day_precision! <= other
+      else
+        min.day_precision! <= other && other <= max.day_precision!
+      end
+    end
+    
+    # call-seq:
+    #     interval.first     -> Date or nil
+    #     interval.first(n)  -> Array
+    #
+    # Returns the first date in the interval, or the first n dates.
+    def first(n = 1)
+      if n > 1
+        (ds = Array(min)).empty? ? ds : ds.concat(ds[0].next(n - 1))        
+      else
+        min
+      end
+    end
+    
+    # call-seq:
+    #     interval.last     -> Date or nil
+    #     interval.last(n)  -> Array
+    #
+    # Returns the last date in the interval, or the last n dates.
+    def last(n = 1)
+      if n > 1
+        (ds = Array(max)).empty? ? ds : ds.concat(ds[0].prev(n - 1))        
+      else
+        max
+      end
+    end
+    
+    # call-seq:
+    #     interval.min                  -> Date or nil
+    #     interval.min { |a,b| block }  -> Date or nil
+    #
+    # Returns the minimum value in the interval. If a block is given, it is
+    # used to compare values (slower). Returns nil if the first date of the
+    # interval is larger than the last or if the interval has an unknown or
+    # open start.
+    def min
+      if block_given?
+        to_a.min(&Proc.new)
+      else
+        case
+        when unknown_start?, !open? && to < from
+          nil
+        when from.day_precision?
+          from
+        when from.month_precision?
+          from.beginning_of_month
+        else
+          from.beginning_of_year
+        end
+      end
+    end
+    
+    def begin
+      min
+    end
+    
+    # call-seq:
+    #     interval.max                  -> Date or nil
+    #     interval.max { |a,b| block }  -> Date or nil
+    #
+    # Returns the maximum value in the interval. If a block is given, it is
+    # used to compare values (slower). Returns nil if the first date of the
+    # interval is larger than the last or if the interval has an unknown or
+    # open end.
+    #
+    # To calculate the dates, precision is taken into account. Thus, the max
+    # Date of "2007/2008" would be 2008-12-31, whilst the max Date of
+    # "2007-12/2008-10" would be 2009-10-31.
+    def max
+      if block_given?
+        to_a.max(&Proc.new)
+      else
+        case
+        when open_end?, unknown_end?, !unknown_start? && to < from
+          nil
+        when to.day_precision? 
+          to
+        when to.month_precision?
+          to.end_of_month
+        else
+          to.end_of_year
+        end
+      end
+    end
+    
+    def end
+      max
+    end
+    
+    def <=>(other)
+      case other
+      when Interval
+        [min, max] <=> [other.min, other.max]
+      when Date
+        cover?(other) ? min <=> other : 0
       else
-        to.end_of_year
+        nil
       end
     end
-   
-  	def edtf
-			[
-				@from.send(@from.respond_to?(:edtf) ? :edtf : :to_s),
-				@to.send(@to.respond_to?(:edtf) ? :edtf : :to_s)
-			].join('/')
-		end
-		
-		alias to_s edtf
-		
+    
+    def ===(other)
+      case other
+      when Interval
+        cover?(other.min) && cover?(other.max)
+      when Date
+        cover?(other)
+      else
+        false
+      end
+    end
+    
+    
+    # Returns the Interval as an EDTF string.
+    def edtf
+      [
+        from.send(from.respond_to?(:edtf) ? :edtf : :to_s),
+        to.send(to.respond_to?(:edtf) ? :edtf : :to_s)
+      ] * '/'
+    end
+    
+    alias to_s edtf
+    
   end
   
 end