edtf 4.0.0 → 4.1.0

data/lib/edtf/parser.y

@@ -56,7 +56,10 @@ rule
                    ;
 
   year : positive_year
-       | '-' positive_year { result = -val[1] }
+       | '-' positive_year {
+         result = -val[1]
+         deprecate :negative_zero if result.zero?
+       }
 
   positive_year : digit digit digit digit {
     result = val.zip([1000,100,10,1]).reduce(0) { |s,(a,b)| s += a * b }
@@ -67,7 +70,7 @@ rule
 
   year_month : year '-' month { result = [val[0], val[2]] }
 
-  # We raise an exception if there are two many days for the month, but
+  # We raise an exception if there are too many days for the month, but
   # do not consider leap years, as the EDTF BNF did not either.
   # NB: an exception will be raised regardless, because the Ruby Date
   # implementation calculates leap years.
@@ -91,7 +94,10 @@ rule
   # NB: Uncertain/approximate Dates are covered by the Level 2 rules
   level_1_expression : unknown | unspecified | level_1_interval | long_year_simple | season
 
-  unknown : U U U U { result = EDTF::Unknown.new }
+  unknown : U U U U {
+    result = EDTF::Unknown.new
+    deprecate :unknown_date
+  }
 
   # uncertain_or_approximate_date : date UA { result = uoa(val[0], val[1]) }
 
@@ -483,12 +489,38 @@ require 'strscan'
 
   @defaults = {
     :level => 2,
-    :debug => false
+    :debug => false,
+    :warn => true
+  }.freeze
+
+  # Input that EDTF-Ruby 5.0 parses differently.
+  # Legacy syntax will be accepted only in legacy mode;
+  # lossy legacy syntax has no ISO 8601-2 equivalent.
+  LEGACY = {
+    combined_qualifier: '`?~` is legacy syntax, use `%`',
+    parentheses: 'parentheses are legacy syntax, ' \
+      'EDTF-Ruby 5.0 qualifies parts from the left instead, e.g. `2004-?06-11`',
+    open: '`open` is legacy syntax, use `..`',
+    unknown: '`unknown` is legacy syntax, leave the interval end empty',
+    unspecified: '`u` is legacy syntax, use `X`',
+    masked: 'masked precision (`198x`) is legacy syntax, ' \
+      'EDTF-Ruby 5.0 reads it as a decade (`198`) or century (`19`)',
+    lowercase_y: '`y` is legacy syntax, use `Y`',
+    lowercase_e: '`e` is legacy syntax, use `E`',
+    negative_zero: '`-0000` is legacy syntax, use `0000`',
+    caret: 'calendars and season qualifiers (`^…`) are legacy syntax, ' \
+      'EDTF-Ruby 5.0 converts hemispheres to seasons, e.g. `2001-21^southern` ' \
+      'to `2001-29`, and drops the rest'
+  }.freeze
+
+  CHANGED = {
+    unknown_date: 'EDTF-Ruby 5.0 parses this as a date ' \
+      'with an unspecified year instead of EDTF::Unknown'
   }.freeze
 
   class << self; attr_reader :defaults; end
 
-  attr_reader :options
+  attr_reader :options, :deprecations
 
   def initialize(options = {})
     @options = Parser.defaults.merge(options)
@@ -508,7 +540,16 @@ require 'strscan'
   def parse!(input)
     @yydebug = debug?
     @src = StringScanner.new(input)
-    do_parse
+    @deprecations = []
+    result = do_parse
+    @deprecations.uniq!
+    warn_deprecations(input) if options[:warn]
+    result
+  end
+
+  # Returns true if the last successful parse used legacy syntax.
+  def legacy?
+    deprecations.any? { |d| LEGACY.key?(d) }
   end
 
   def on_error(tid, value, stack)
@@ -516,6 +557,16 @@ require 'strscan'
       "failed to parse date: unexpected '#{value}' at #{stack.inspect}"
   end
 
+  def deprecate(name)
+    @deprecations << name
+  end
+
+  def warn_deprecations(input)
+    return if deprecations.empty?
+    messages = deprecations.map { |d| LEGACY[d] || CHANGED[d] }
+    warn "EDTF #{input.inspect}: #{messages.join('; ')}", category: :deprecated
+  end
+
   def apply_uncertainty(date, uncertainty, scope = nil)
     uncertainty.each do |u|
       scope.nil? ? date.send(u) : date.send(u, scope)
@@ -532,6 +583,7 @@ require 'strscan'
     # when @src.scan(/\s+/)
       # ignore whitespace
     when @src.scan(/\(/)
+      deprecate :parentheses
       ['(', @src.matched]
     # when @src.scan(/\)\?~-/)
     #   [:PUA, [:uncertain!, :approximate!]]
@@ -554,6 +606,7 @@ require 'strscan'
     when @src.scan(/Z/)
       [:Z, @src.matched]
     when @src.scan(/\?~/)
+      deprecate :combined_qualifier
       [:UA, [:uncertain!, :approximate!]]
     when @src.scan(/%/)
       [:UA, [:uncertain!, :approximate!]]
@@ -562,22 +615,29 @@ require 'strscan'
     when @src.scan(/~/)
       [:UA, [:approximate!]]
     when @src.scan(/open/i)
+      deprecate :open
       [:OPEN, :open]
     when @src.scan(/unkn?own/i) # matches 'unkown' typo too
+      deprecate :unknown
       [:UNKNOWN, :unknown]
     when @src.scan(/u/)
+      deprecate :unspecified
       [:U, @src.matched]
     when @src.scan(/X/)
       [:U, @src.matched]
     when @src.scan(/x/)
+      deprecate :masked
       [:X, @src.matched]
     when @src.scan(/y/i)
+      deprecate :lowercase_y if @src.matched == 'y'
       [:LONGYEAR, @src.matched]
     when @src.scan(/e/i)
+      deprecate :lowercase_e if @src.matched == 'e'
       [:E, @src.matched]
     when @src.scan(/\+/)
       ['+', @src.matched]
     when @src.scan(/-\(/)
+      deprecate :parentheses
       ['-(', @src.matched]
     when @src.scan(/-/)
       ['-', @src.matched]
@@ -590,6 +650,7 @@ require 'strscan'
     when @src.scan(/\s*,\s*/)
       [',', ',']
     when @src.scan(/\^\w+/)
+      deprecate :caret
       ['^', @src.matched[1..-1]]
     when @src.scan(/\d/)
       [@src.matched, @src.matched.to_i]

data/lib/edtf/version.rb

@@ -1,3 +1,3 @@
 module EDTF
-  VERSION = '4.0.0'.freeze
+  VERSION = '4.1.0'.freeze
 end

data/lib/edtf.rb

@@ -1,33 +1,3 @@
-#--
-# EDTF-Ruby
-# Copyright 2011 Sylvester Keil. All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-# 
-#  1. Redistributions of source code must retain the above copyright notice,
-#     this list of conditions and the following disclaimer.
-# 
-#  2. Redistributions in binary form must reproduce the above copyright
-#     notice, this list of conditions and the following disclaimer in the
-#     documentation and/or other materials provided with the distribution.
-# 
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS
-# OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
-# NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# 
-# The views and conclusions contained in the software and documentation are
-# those of the authors and should not be interpreted as representing official
-# policies, either expressed or implied, of the copyright holder.
-#++
-
 require 'date'
 require 'time'
 
@@ -64,7 +34,7 @@ require 'edtf/extensions'
 # Date/Time Format (EDTF). See the `EDTF::ExtendedDate` module for an
 # overview of the features added to the Ruby `Date` class.
 #
-# To parse EDTF strings use either `Date.edtf` of `EDTF.parse`.
+# To parse EDTF strings use `EDTF.parse` or `EDTF()`.
 #
 module EDTF
 
@@ -77,7 +47,31 @@ module EDTF
   end
   
   def parse!(input, options = {})
-    ::Date.edtf!(input, options)
+    Parser.new(options).parse!(input)
+  end
+
+  def legacy?(input)
+    parser = Parser.new(warn: false)
+    !parser.parse(input).nil? && parser.legacy?
+  end
+end
+
+module Kernel
+  private
+
+  # Converts value to an EDTF object:
+  # strings are parsed, times become date-times,
+  # dates and other EDTF objects are returned unchanged.
+  def EDTF(value)
+    case value
+    when String
+      EDTF.parse!(value)
+    when Time
+      value.to_datetime
+    when Date, EDTF::Season, EDTF::Epoch, EDTF::Interval, EDTF::Set, EDTF::Unknown
+      value
+    else
+      raise TypeError, "can't convert #{value.class} into EDTF"
+    end
   end
-    
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: edtf
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Sylvester Keil
@@ -95,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.22
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Extended Date/Time Format for Ruby.
 test_files: []