edtf 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68cf5a59b655ee503dfda487dd719422299c40ee1744baeb93605b5b08bd0c9f
-  data.tar.gz: 2b8e4a4e41c46f9607057c2b61720d3fce35acae2afa73ea112ff3bfdc03dc5e
+  metadata.gz: da8f3ed7204b150a35b07df4507742e265a9e78684956a824a1803da966c8fc8
+  data.tar.gz: 612e35c7e583ca68a51cc81f22314c60ac7aaefbffde79e243b2de428ded3589
 SHA512:
-  metadata.gz: 34e2bf30004ba2eb3389d69fd9244cff29ddcf915e477e894b513116365efb0862585d2fa078786d5f40c22cfbddfec23d26a361886be0a78013f1b4457e0b93
-  data.tar.gz: fa871f182f1ec791e36946c0a8a5127323c6b4da1aa6915b625f180a2e0698d586f6452d4d969f2d9f4345195838a92a4ee6414068354334f79a27ceb6fc0000
+  metadata.gz: a71e612f246046dc6d6706834b5fbb0a57b68bcb248eaa2e2a761af6b07c6df169492ba607c82a3df2c2187be6896fa239437b70c34a009e8b7e3324f8501520
+  data.tar.gz: b8caf26e31f0b665e2e4b1ffd7ac464ef8339c879a4b363a06b89f38b1823586e7bb2797ded205cb721a31dd4bbe5e7c3ac16e1e749c45a9a39e6d516ae884f5

data/README.md

@@ -29,17 +29,52 @@ because of many functional overlaps
 ### ISO 8601-2
 
 A variation of EDTF has been adopted by the ISO 8601-2 standard.
-EDTF-Ruby does not support this new version of EDTF yet,
-but if you are curious,
-[EDTF.js](https://github.com/inukshuk/edtf.js), an ES6 implementation
-is already available.
+EDTF-Ruby 5.0 will switch to this version of EDTF.
+
+Preparing for EDTF-Ruby 5.0
+---------------------------
+EDTF-Ruby 5.0 will accept the older draft syntax
+only in an opt-in legacy mode, and print ISO 8601-2 syntax only.
+Version 4.1 helps you prepare.
+
+Enable deprecation warnings
+to see which input uses legacy syntax
+and which methods will go away:
+
+    $ RUBYOPT=-W:deprecated bundle exec rake
+    EDTF "2004/open": `open` is legacy syntax, use `..`
+
+In code, use `Warning[:deprecated] = true` instead.
+To audit stored dates without warnings, use `EDTF.legacy?`,
+e.g. to print each line of a file that uses legacy syntax:
+
+    $ ruby -redtf -ne 'print if EDTF.legacy?($_.chomp)' dates.txt
+
+You can switch most legacy syntax to ISO 8601-2 right away.
+Parentheses and masked precision (`198x`) have no replacement in 4.1;
+EDTF-Ruby 5.0 converts them in legacy mode.
+Calendars and season qualifiers (`^…`) are not part of ISO 8601-2;
+EDTF-Ruby 5.0 converts hemispheres to seasons (`2001-21^southern` to `2001-29`).
+
+In your code:
+* Replace `Date.edtf` and `Date.edtf!`
+  with `EDTF.parse`, `EDTF.parse!`, or `EDTF()`.
+  `EDTF()` converts strings, times, and dates to EDTF objects,
+  raising an error if it cannot.
+* EDTF objects will be immutable.
+  Instead of the bang! methods, use `with` for a modified copy:
+
+      > EDTF('2004-06-11').with(precision: :year, approximate: :year).edtf
+      => "2004~"
+
+* `XXXX` will be a date with an unspecified year instead of an `EDTF::Unknown`.
 
 Quickstart
 ----------
 EDTF Ruby is implemented as an extension to the regular Ruby date/time classes.
-You can parse EDTF strings either using `Date.edtf` or `EDTF.parse`
-(both methods come with an alternative bang! version,
-that will raise an error if the string cannot be parsed
+You can parse EDTF strings using `EDTF.parse`
+(or its bang! version `EDTF.parse!`, or `EDTF()`,
+which will raise an error if the string cannot be parsed
 instead of silently returning nil);
 if given a valid EDTF string
 the return value will either be an (extended) `Date`,
@@ -130,7 +165,7 @@ whilst uncertain could be something completely different
 Here are a few examples of how you can access
 the uncertain/approximate state of dates in Ruby:
 
-    > d = Date.edtf('1984?')
+    > d = EDTF('1984?')
     > d.uncertain?
     => true
     > d.uncertain? :year
@@ -151,7 +186,7 @@ In addition, EDTF supports *unspecified* date parts.
 EDTF-Ruby provides parsing for both the draft and finalized EDTF specifications,
 with output meeting the requirements of the final specification:
 
-    > d = Date.edtf('1999-03-XX')
+    > d = EDTF('1999-03-XX')
     > d.unspecified?
     => true
     > d.unspecified? :year
@@ -162,7 +197,7 @@ with output meeting the requirements of the final specification:
     > d.edtf
     => "1999-XX-XX"
 
-    > draft_d = Date.edtf('1999-03-uu')
+    > draft_d = EDTF('1999-03-uu')    # legacy syntax
     > draft_d.edtf
     => "1999-03-XX"
 
@@ -172,12 +207,12 @@ do not factor into date calculations
 
 EDTF long or scientific years are mapped to normal date instances.
 
-    > Date.edtf('y-17e7').year
+    > EDTF('Y-17E7').year
     => -170000000
 
 When printing date strings, EDTF-Ruby will try to avoid nested parentheses:
 
-    > Date.edtf("(1999-(02)~-23)?").edtf
+    > EDTF("(1999-(02)~-23)?").edtf
     => "1999?-(02)?~-23?"
 
 
@@ -188,7 +223,7 @@ the EDTF-Ruby parser will return an instance of `EDTF::Interval`;
 intervals mimic regular Ruby ranges,
 but offer additional functionality.
 
-    > d = Date.edtf('1984-06?/2004-08?')
+    > d = EDTF('1984-06?/2004-08?')
     > d.from.uncertain?
     => true
     > d.include?(Date.new(1987,04,13))
@@ -215,7 +250,7 @@ There are 243 months between 1984-06-01 and 2004-08-31.
 Here we iterate through the interval in 36-month steps
 and map each date to the year.
 
-    > Date.edtf('1582-10-01/1582-10-31').length
+    > EDTF('1582-10-01/1582-10-31').length
     => 31
 
 This interval has day precision,
@@ -225,9 +260,9 @@ so the ten days skipped by the Gregorian calendar reform are included.
 
 Intervals can be open or have unknown start or end dates.
 
-    > Date.edtf('2004/open').open?
+    > EDTF('2004/..').open?
     => true
-    > Date.edtf('2004/open').cover?(Date.today)
+    > EDTF('2004/..').cover?(Date.today)
     => true
 
 ### Sets
@@ -238,7 +273,7 @@ or inclusive lists.
 In EDTF-Ruby, these are covered by the class `EDTF::Set`
 and the `choice` attribute.
 
-    > s = Date.edtf('{1667,1668, 1670..1672}')
+    > s = EDTF('{1667,1668, 1670..1672}')
     > s.choice?
     => false
     > s.choice!
@@ -249,9 +284,9 @@ As you can see above,
 EDTF-Ruby remembers which parts of the set were specified as a range;
 ranges are however enumerated for membership tests:
 
-    > s.include?(Date.edtf('1669'))
+    > s.include?(EDTF('1669'))
     => false
-    > s.include?(Date.edtf('1671'))
+    > s.include?(EDTF('1671'))
     => true
 
 Even though we're still aware
@@ -282,7 +317,7 @@ to define decades or centuries.
 EDTF-Ruby maps these to dedicated intervals
 which always cover 10 or 100 years, respectively.
 
-    > d = Date.edtf!('196x')
+    > d = EDTF('196x')
     > d.edtf
     => "196x"
     > d.class
@@ -306,7 +341,7 @@ which allow you to access the seasons by the names
 spring, summer, autumn (or fall), and winter, respectively.
 You can also use the more neutral taxonomy of first, second, third, fourth.
 
-    > w = Date.edtf!('2003-24')
+    > w = EDTF('2003-24')
     > w.winter?
     => true
     > s = w.succ

data/lib/edtf/date.rb

@@ -24,13 +24,13 @@ class Date
     end
     
     def edtf(input, options = {})
-      edtf!(input, options)
-    rescue
-      nil
+      warn '`Date.edtf` is deprecated, use `EDTF.parse`', category: :deprecated, uplevel: 1
+      ::EDTF.parse(input, options)
     end
 
     def edtf!(input, options = {})
-      ::EDTF::Parser.new(options).parse!(input)
+      warn '`Date.edtf!` is deprecated, use `EDTF.parse!` or `EDTF()`', category: :deprecated, uplevel: 1
+      ::EDTF.parse!(input, options)
     end
   end
 
@@ -80,6 +80,17 @@ class Date
   end
 
 
+  # Returns a copy with the given EDTF attributes replaced.
+  def with(precision: self.precision,
+           uncertain: PRECISION.select { |p| uncertain?(p) },
+           approximate: PRECISION.select { |p| approximate?(p) })
+    date = dup
+    date.precision = precision
+    date.uncertain.certain!.uncertain!(uncertain)
+    date.approximate.certain!.uncertain!(approximate)
+    date
+  end
+
   # Returns this Date's precision.
   def precision
     @precision ||= :day

data/lib/edtf/interval.rb

@@ -11,12 +11,12 @@ module EDTF
   # containing exactly four dates with year precision. This is also reflected
   # in membership tests.
   #
-  #     Date.edtf('2003/2006').length                           -> 4
+  #     EDTF('2003/2006').length                     -> 4
   #
-  #     Date.edtf('2003/2006').include? Date.edtf('2004')       -> true
-  #     Date.edtf('2003/2006').include? Date.edtf('2004-03')    -> false
+  #     EDTF('2003/2006').include? EDTF('2004')      -> true
+  #     EDTF('2003/2006').include? EDTF('2004-03')   -> false
   #
-  #     Date.edtf('2003/2006').cover? Date.edtf('2004-03')      -> true
+  #     EDTF('2003/2006').cover? EDTF('2004-03')     -> true
   #
   class Interval