edtf 4.1.1 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,138 +1,154 @@
1
1
  EDTF-Ruby
2
2
  =========
3
- [![ci](https://github.com/inukshuk/edtf-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/inukshuk/edtf-ruby/actions/workflows/ci.yml)
4
-
5
3
  EDTF-Ruby comprises a parser and an API implementation
6
- of the [Extended Date/Time Format standard](https://www.loc.gov/standards/datetime/).
4
+ of the [Extended Date/Time Format][edtf] (EDTF)
5
+ as specified by ISO 8601-2.
6
+
7
+ EDTF-Ruby 5.0 switches from the EDTF draft syntax to ISO 8601-2;
8
+ to upgrade from 4.x, see [UPGRADING.md][upgrading].
9
+ For EDTF-Ruby 4.x see the [legacy branch][legacy].
10
+
11
+ [edtf]: https://www.loc.gov/standards/datetime/
12
+ [legacy]: https://github.com/inukshuk/edtf-ruby/tree/legacy
13
+ [upgrading]: UPGRADING.md
7
14
 
8
15
 
9
16
  Compatibility
10
17
  -------------
11
- EDTF-Ruby parser implements all levels and features of the EDTF specification
12
- (version September 16, 2011).
13
- With the following known caveats:
14
-
15
- * In the latest revision of the EDTF specification
16
- alternative versions of partial uncertain/approximate strings were introduced
17
- (with or without nested parentheses);
18
- EDTF-Ruby currently uses the version that tries to reduce parentheses for printing
19
- as we find that one easier to read;
20
- the parser accepts all valid dates using this approach,
21
- plus some dates using nested expressions
22
- (the parser will not accept some of the more complex examples, though).
23
-
24
- EDTF-Ruby is tested on Ruby 3.3 and later, and on JRuby.
25
- Active Support's date extensions are currently listed as a dependency,
26
- because of many functional overlaps
27
- (versions 3.x through 8.x are supported).
28
-
29
- ### ISO 8601-2
30
-
31
- A variation of EDTF has been adopted by the ISO 8601-2 standard.
32
- EDTF-Ruby 5.0 will switch to this version of EDTF.
33
-
34
- Preparing for EDTF-Ruby 5.0
35
- ---------------------------
36
- EDTF-Ruby 5.0 will accept the older draft syntax
37
- only in an opt-in legacy mode, and print ISO 8601-2 syntax only.
38
- Version 4.1 helps you prepare.
39
-
40
- Enable deprecation warnings
41
- to see which input uses legacy syntax
42
- and which methods will go away:
18
+ EDTF-Ruby fully implements EDTF levels 0, 1, and 2
19
+ as specified by ISO 8601-2 with the following exceptions:
43
20
 
44
- $ RUBYOPT=-W:deprecated bundle exec rake
45
- EDTF "2004/open": `open` is legacy syntax, use `..`
21
+ 1. Uncertain or approximate seasons (`2001-21?`, `2001?-21`)
22
+ and seasons with unspecified years (`200X-21`).
23
+ 2. Offsets without a colon after an extended date
24
+ (`2004-01-01T10:10:10+0230`).
25
+ 3. Seasons in intervals (`2001-21/2002-22`).
46
26
 
47
- In code, use `Warning[:deprecated] = true` instead.
48
- To audit stored dates without warnings, use `EDTF.legacy?`,
49
- e.g. to print each line of a file that uses legacy syntax:
27
+ The first two extensions are on by default;
28
+ see [Parser options][options] to turn them on or off.
50
29
 
51
- $ ruby -redtf -ne 'print if EDTF.legacy?($_.chomp)' dates.txt
30
+ EDTF-Ruby still reads the draft syntax of earlier EDTF versions
31
+ (`?~`, parentheses, `u`, `open`, `unknown`, …)
32
+ and warns when deprecation warnings are enabled;
33
+ see [Legacy syntax][legacy-syntax].
34
+
35
+ EDTF-Ruby is tested on Ruby 3.3 and later.
36
+ It does not depend on ActiveSupport anymore,
37
+ but works fine alongside it and on Rails;
38
+ see [Rails and ActiveSupport][rails].
52
39
 
53
- You can switch most legacy syntax to ISO 8601-2 right away.
54
- Parentheses and masked precision (`198x`) have no replacement in 4.1;
55
- EDTF-Ruby 5.0 converts them in legacy mode.
56
- Calendars and season qualifiers (`^…`) are not part of ISO 8601-2;
57
- EDTF-Ruby 5.0 converts hemispheres to seasons (`2001-21^southern` to `2001-29`).
40
+ [options]: #parser-options
41
+ [legacy-syntax]: #legacy-syntax
42
+ [rails]: #rails-and-activesupport
58
43
 
59
- In your code:
60
- * Replace `Date.edtf` and `Date.edtf!`
61
- with `EDTF.parse`, `EDTF.parse!`, or `EDTF()`.
62
- `EDTF()` converts strings, times, and dates to EDTF objects,
63
- raising an error if it cannot.
64
- * EDTF objects will be immutable.
65
- Instead of the bang! methods, use `with` for a modified copy:
66
44
 
67
- > EDTF('2004-06-11').with(precision: :year, approximate: :year).edtf
68
- => "2004~"
45
+ Installation
46
+ ------------
47
+ $ gem install edtf
48
+
49
+ Or add it to your Gemfile.
69
50
 
70
- * `XXXX` will be a date with an unspecified year instead of an `EDTF::Unknown`.
71
51
 
72
52
  Quickstart
73
53
  ----------
74
- EDTF Ruby is implemented as an extension to the regular Ruby date/time classes.
75
- You can parse EDTF strings using `EDTF.parse`
76
- (or its bang! version `EDTF.parse!`, or `EDTF()`,
77
- which will raise an error if the string cannot be parsed
78
- instead of silently returning nil);
79
- if given a valid EDTF string
80
- the return value will either be an (extended) `Date`,
81
- `EDTF::Interval`, `EDTF::Set`, `EDTF::Epoch` or `EDTF::Season` instance.
54
+ Parse EDTF strings with `EDTF.parse`,
55
+ which returns nil if the string cannot be parsed,
56
+ or with `EDTF.parse!` or `EDTF()`,
57
+ which raise an ArgumentError instead.
58
+
59
+ require 'edtf'
60
+
61
+ EDTF.parse('2016-XX') #-> #<EDTF::Date 2016-XX>
62
+ EDTF.parse('not a date') #-> nil
63
+ EDTF('2016-04~/2016-05') #-> #<EDTF::Interval 2016-04~/2016-05>
64
+
65
+ `EDTF()` also converts Ruby dates and times,
66
+ parse results (see [Parser][parser]),
67
+ and returns EDTF objects unchanged.
68
+
69
+ EDTF(Date.new(2016, 5, 31)) #-> #<EDTF::Date 2016-05-31>
70
+
71
+ EDTF-Ruby has the following types:
72
+ `EDTF::Date` (a Ruby `Date`) and `EDTF::DateTime` (a Ruby `Time`),
73
+ `EDTF::Decade` and `EDTF::Century`,
74
+ `EDTF::Season`,
75
+ `EDTF::Interval`,
76
+ `EDTF::Set` (one of a set) and `EDTF::List` (all members of a set).
77
+
78
+ Each EDTF string stands for a period of time,
79
+ so all types share an interface (`EDTF::Period`) exposing:
80
+ the corresponding EDTF string,
81
+ the first and last day of the period,
82
+ its precision, and its values.
83
+
84
+ EDTF('2016?').edtf #-> "2016?"
85
+ EDTF('2016?').to_s #-> "2016?"
86
+
87
+ `edtf` and `to_s` return the ISO 8601-2 (EDTF) string;
88
+ `iso8601` returns the ISO 8601-1 string of the first day, as in Ruby:
89
+
90
+ EDTF('2016?').iso8601 #-> "2016-01-01"
82
91
 
83
- Given any of these instances,
84
- you can print the corresponding EDTF string using the `#edtf` method.
92
+ EDTF('2016-02').begin.to_s #-> "2016-02-01"
93
+ EDTF('2016-02').end.to_s #-> "2016-02-29"
94
+ EDTF('2016-02').precision #-> :month
85
95
 
86
- ### Dates
96
+ EDTF('2016-02-2X').begin.to_s #-> "2016-02-20"
97
+ EDTF('2016-02-2X').end.to_s #-> "2016-02-29"
87
98
 
99
+ EDTF('[..2016,2017]').begin #-> nil
100
+ EDTF('[..2016,2017]').end.to_s #-> "2017-12-31"
101
+
102
+ EDTF('2016-34').begin.to_s #-> "2016-04-01"
103
+ EDTF('2016-34').end.to_s #-> "2016-06-30"
104
+
105
+ EDTF('2016?-02').values #-> [2016, 2]
106
+
107
+ All EDTF objects are frozen.
108
+ Use `with` to return a modified copy.
109
+
110
+ EDTF('2016-05?').with(approximate: true).edtf #-> "2016-05%"
111
+
112
+ [parser]: #parser
113
+
114
+
115
+ Dates
116
+ -----
88
117
  Most of the EDTF features deal with dates;
89
- EDTF-Ruby implements these by extending Active Support's version
90
- of the regular Ruby Date class.
91
- The library intends to be transparent to Ruby's regular API,
92
- i.e., every Date instance should act as you would normally expect
118
+ EDTF-Ruby implements these by extending the regular Ruby Date class.
119
+ Every EDTF date acts as you would normally expect,
93
120
  but provides additional functionality.
94
121
 
95
122
  Most notably, EDTF dates come in day, month, or year precision.
96
123
  This is a subtle difference that determines how many other methods work.
97
124
  For instance:
98
125
 
99
- > Date.today.precision
100
- => :day
101
- > Date.today
102
- => Thu, 10 Nov 2011
103
- > Date.today.succ
104
- => Fri, 11 Nov 2011
105
- > Date.today.month_precision!.succ
106
- => Sat, 10 Dec 2011
107
-
108
- As you can see, dates have day precision by default;
109
- after setting the date's precision to month, however,
110
- the natural successor is not the next day,
111
- but a day a month from now.
126
+ EDTF('2016-05-31').succ.edtf #-> "2016-06-01"
127
+ EDTF('2016-05').succ.edtf #-> "2016-06"
128
+ EDTF('2016').succ.edtf #-> "2017"
129
+
130
+ The natural successor of a date with month precision
131
+ is not the next day, but the next month.
112
132
  Always keep precision in mind when comparing dates, too:
113
133
 
114
- > Date.new(1966).year_precision! == Date.new(1966)
115
- => false
134
+ EDTF('1966') == EDTF('1966-01-01') #-> false
116
135
 
117
136
  The year 1966 is not equal to the January 1st, 1966.
118
- You can set a date's precision directly,
119
- or else use the dedicated bang! methods:
120
-
121
- > d = Date.new(1993)
122
- > d.day_precision? # -> true
123
- > d.edtf
124
- => "1993-01-01"
125
- > d.month_precision!
126
- > d.edtf
127
- => "1993-01"
128
- > d.year_precision!
129
- > d.edtf
130
- => "1993"
131
- > d.day_precision? # -> false
132
- > d.year_precision? # -> true
133
-
134
- In the examples above, you also see that the `#edtf` method
135
- will print a different string depending on the date's current precision.
137
+ To change a date's precision, use `with`:
138
+
139
+ d = EDTF('1993-01-01')
140
+ d.with(precision: :month).edtf #-> "1993-01"
141
+ d.with(precision: :year).edtf #-> "1993"
142
+
143
+ In the examples above, you also see that `edtf`
144
+ prints a different string depending on the date's precision.
145
+
146
+ Date math (`+`, `-`, `>>`, `<<`, or `next_day`) returns plain Ruby dates,
147
+ because the result no longer stands for the same EDTF string:
148
+
149
+ (EDTF('2016-05?') + 1).class #-> Date
150
+
151
+ ### Unspecified, uncertain, and approximate dates
136
152
 
137
153
  The second important extension is that dates can be uncertain and or approximate.
138
154
  The distinction between the two may seem somewhat contrived,
@@ -152,7 +168,7 @@ you don't recall the exact date,
152
168
  but you know it must have been sometime between Christmas and New Year's.
153
169
  Come to think of it, you don't remember the year either,
154
170
  but you must have been around ten years old.
155
- Using EDTF, you could write something like "1993~-12-(27)~":
171
+ Using EDTF, you could write something like "1993~-12-~27":
156
172
  this indicates that both the year and the day are approximations:
157
173
  perhaps the day is not the 27th but it is somewhere close.
158
174
 
@@ -162,223 +178,386 @@ approximate always means close to the actual number,
162
178
  whilst uncertain could be something completely different
163
179
  (just as there is a large temporal distance between 1638 and 1683).
164
180
 
165
- Here are a few examples of how you can access
166
- the uncertain/approximate state of dates in Ruby:
181
+ EDTF-Ruby keeps track of qualified dates using bitmasks (`EDTF::Bitmask`).
182
+ You can ask about the whole date, or about its year, month, or day:
183
+
184
+ EDTF('2016-05?').uncertain? #-> true
185
+ EDTF('2016-05?').approximate? #-> false
186
+ EDTF('2016-05?').uncertain?(:month) #-> true
187
+ EDTF('2016-05?').uncertain?(:day) #-> false
188
+ EDTF('2016-?05').uncertain?(:year) #-> false
189
+ EDTF('2016-?05').uncertain?(:month) #-> true
190
+
191
+ EDTF('201X-XX').unspecified?(:year) #-> true
192
+ EDTF('1999-XX').unspecified.to_s #-> "YYYY-XX-DD"
193
+
194
+ When printing qualified dates,
195
+ EDTF-Ruby finds the shortest rendition of the qualification symbols,
196
+ so you can use it to normalize EDTF strings:
197
+
198
+ EDTF('?2016-?05-31').edtf #-> "2016-05?-31"
199
+ EDTF('?2016-?05~-31').edtf #-> "2016-05%-31"
200
+ EDTF::Date.new(2004, 6, 11, uncertain: :year, approximate: :day).edtf #-> "2004?-06-~11"
201
+
202
+ Uncertain, approximate, and unspecified parts
203
+ do not factor into comparisons;
204
+ dates are equal if they stand for the same period,
205
+ and `eql?` (used for hash keys) tells them apart:
206
+
207
+ EDTF('1906') == EDTF('1906?') #-> true
208
+ EDTF('1906').eql?(EDTF('1906?')) #-> false
167
209
 
168
- > d = EDTF('1984?')
169
- > d.uncertain?
170
- => true
171
- > d.uncertain? :year
172
- => true
173
- > d.uncertain? :day
174
- => false
175
- > d.approximate!
176
- > d.edtf
177
- => "1984?~"
178
- > d.month_precision!
179
- > d.approximate! :month
180
- > d.edtf
181
- => "1984?-01~"
210
+ Unspecified digits widen a date's bounds,
211
+ and its successor steps over them:
182
212
 
183
- As you can see above, you can use the bang! methods to set individual date parts.
213
+ EDTF('1999-03-XX').end.to_s #-> "1999-03-31"
214
+ EDTF('201X-05').succ.edtf #-> "201X-06"
184
215
 
185
- In addition, EDTF supports *unspecified* date parts.
186
- EDTF-Ruby provides parsing for both the draft and finalized EDTF specifications,
187
- with output meeting the requirements of the final specification:
216
+ EDTF-Ruby will not parse impossible unspecified dates.
217
+ For instance, none of the following examples can be valid dates:
188
218
 
189
- > d = EDTF('1999-03-XX')
190
- > d.unspecified?
191
- => true
192
- > d.unspecified? :year
193
- => false
194
- > d.unspecified? :day
195
- => true
196
- > d.unspecified! :month
197
- > d.edtf
198
- => "1999-XX-XX"
219
+ EDTF.parse('2016-02-3X') #-> nil (a day in February cannot start with a 3)
220
+ EDTF.parse('2016-2X-XX') #-> nil (there are only 12 months)
221
+ EDTF.parse('2016-XX-32') #-> nil (no month has 32 days)
199
222
 
200
- > draft_d = EDTF('1999-03-uu') # legacy syntax
201
- > draft_d.edtf
202
- => "1999-03-XX"
223
+ ### Enumerating dates
203
224
 
204
- All three, uncertain, approximate, and unspecified attributes
205
- do not factor into date calculations
206
- (like comparisons or successors etc.).
225
+ Dates step by their precision:
207
226
 
208
- EDTF long or scientific years are mapped to normal date instances.
227
+ EDTF('2016-02-28').succ.edtf #-> "2016-02-29"
228
+ EDTF('2017-02-28').succ.edtf #-> "2017-03-01"
209
229
 
210
- > EDTF('Y-17E7').year
211
- => -170000000
230
+ `upto` and `downto` yield all the dates, by precision,
231
+ from one date to another:
212
232
 
213
- When printing date strings, EDTF-Ruby will try to avoid nested parentheses:
233
+ EDTF('2016-05').upto(EDTF('2016-07')).map(&:edtf) #-> ["2016-05", "2016-06", "2016-07"]
234
+ EDTF('2016-07').downto(EDTF('2016-05')).map(&:edtf) #-> ["2016-07", "2016-06", "2016-05"]
214
235
 
215
- > EDTF("(1999-(02)~-23)?").edtf
216
- => "1999?-(02)?~-23?"
236
+ ### Years
217
237
 
238
+ EDTF years beyond four digits are written with a `Y` prefix,
239
+ and may use an exponent:
218
240
 
219
- ### Intervals
241
+ EDTF('Y170000002').year #-> 170000002
242
+ EDTF('Y-17E7').edtf #-> "Y-170000000"
220
243
 
244
+ Years may have significant digits,
245
+ which widen their bounds:
246
+
247
+ EDTF('1950S2').end.to_s #-> "1999-12-31"
248
+ EDTF::Date.new(1950, significant: 2).edtf #-> "1950S2"
249
+
250
+ ISO 8601 numbers years astronomically:
251
+ `0000` is 1 BC and `-0001` is 2 BC,
252
+ so the first century BC is `-0099/0000`.
253
+ With `year_zero: false`, years before 1 are read and written historically,
254
+ without a year 0, but stored astronomically:
255
+
256
+ EDTF.parse('-0001', year_zero: false).year #-> 0
257
+ EDTF.parse('-0001', year_zero: false).edtf #-> "-0001"
258
+ EDTF.parse('0000', year_zero: false) #-> nil
259
+
260
+
261
+ Date-times
262
+ ----------
263
+ EDTF date-times are regular Ruby times,
264
+ which know whether their string had an offset.
265
+ Without one, a time is floating;
266
+ EDTF-Ruby keeps it on the UTC clock, never in the system's time zone.
267
+
268
+ t = EDTF('2004-01-01T10:10:10+05:00')
269
+ t.offset #-> 300
270
+ t == EDTF('2004-01-01T05:10:10Z') #-> true
271
+ EDTF('2004-01-01T10:10:10').floating? #-> true
272
+
273
+ Date-times come in hour, minute, or second precision;
274
+ like dates, they step by their precision,
275
+ and a time to the hour covers the whole hour:
276
+
277
+ EDTF('2004-01-01T10').precision #-> :hour
278
+ EDTF('2004-01-01T10:30').succ.edtf #-> "2004-01-01T10:31"
279
+ EDTF('2004-01-01T10').cover?(EDTF('2004-01-01T10:30')) #-> true
280
+
281
+ Compared with dates,
282
+ a time counts as its own calendar date in its own offset,
283
+ after the whole day:
284
+
285
+ EDTF('2004-01-01') < t #-> true
286
+ EDTF('2004').cover?(t) #-> true
287
+
288
+
289
+ Intervals
290
+ ---------
221
291
  If you parse an EDTF interval,
222
- the EDTF-Ruby parser will return an instance of `EDTF::Interval`;
223
- intervals mimic regular Ruby ranges,
224
- but offer additional functionality.
292
+ EDTF-Ruby returns an instance of `EDTF::Interval`;
293
+ intervals behave like regular Ruby ranges,
294
+ but are dedicated to EDTF periods.
295
+ Most importantly, intervals use the precision of their start
296
+ when generating the set of contained values and for membership tests.
225
297
 
226
- > d = EDTF('1984-06?/2004-08?')
227
- > d.from.uncertain?
228
- => true
229
- > d.include?(Date.new(1987,04,13))
230
- => false
298
+ i = EDTF('1984-06?/2004-08?')
299
+ i.from.uncertain? #-> true
300
+ i.include?(Date.new(1987, 4, 13)) #-> false
231
301
 
232
- The day is not included because interval has month precision.
302
+ The day is not included because the interval has month precision.
233
303
  However:
234
304
 
235
- > d.cover?(Date.new(1987,04,13))
236
- => true
305
+ i.cover?(Date.new(1987, 4, 13)) #-> true
237
306
 
238
307
  The day is still covered by the interval.
239
- In general, optimized in the same way that Ruby optimizes numeric ranges.
240
- Additionally, precision plays into the way intervals are enumerated:
308
+ Precision also plays into the way intervals are enumerated:
241
309
 
242
- > d.length
243
- => 243
310
+ i.count #-> 243
244
311
 
245
312
  There are 243 months between 1984-06-01 and 2004-08-31.
246
313
 
247
- > d.step(36).map(&:year)
248
- => [1984, 1987, 1990, 1993, 1996, 1999, 2002]
314
+ i.each_slice(36).map { |months| months.first.year } #-> [1984, 1987, 1990, 1993, 1996, 1999, 2002]
249
315
 
250
316
  Here we iterate through the interval in 36-month steps
251
- and map each date to the year.
317
+ and map each step to its first year.
318
+ This also works with varying precisions:
252
319
 
253
- > EDTF('1582-10-01/1582-10-31').length
254
- => 31
320
+ EDTF('2015-10/2016').map(&:edtf).first(4) #-> ["2015-10", "2015-11", "2015-12", "2016-01"]
321
+
322
+ EDTF('1582-10-01/1582-10-31').count #-> 31
255
323
 
256
324
  This interval has day precision,
257
325
  so 31 is the number of days in October 1582:
258
326
  EDTF-Ruby uses the proleptic Gregorian calendar,
259
327
  so the ten days skipped by the Gregorian calendar reform are included.
328
+ Other calendars Ruby supports work, too:
329
+
330
+ EDTF.parse('1500-02-29', calendar: :julian) #-> #<EDTF::Date 1500-02-29 julian>
331
+ EDTF.parse('1500-02-29') #-> nil
260
332
 
261
- Intervals can be open or have unknown start or end dates.
333
+ Dates, seasons, decades and centuries keep their calendar
334
+ for their bounds, stepping, and digits;
335
+ `julian`, `gregorian`, and `new_start` convert to plain dates,
336
+ as for Ruby dates.
262
337
 
263
- > EDTF('2004/..').open?
264
- => true
265
- > EDTF('2004/..').cover?(Date.today)
266
- => true
338
+ Intervals can have open (`..`) or unknown (empty) ends,
339
+ whose bounds are nil:
267
340
 
268
- ### Sets
341
+ EDTF('2004/..').open? #-> true
342
+ EDTF('2004/..').cover?(Date.today) #-> true
343
+ EDTF('/2004').unknown? #-> true
269
344
 
345
+ An interval may end at 24:00, the end of a day:
346
+ that is the next day's midnight,
347
+ and it is written as it was read:
348
+
349
+ i = EDTF('2004-01-01T10:00/2004-01-01T24:00')
350
+ i.end.to_s #-> "2004-01-02"
351
+ i.edtf #-> "2004-01-01T10:00/2004-01-01T24:00"
352
+ i.to.t24? #-> true
353
+
354
+
355
+ Sets and lists
356
+ --------------
270
357
  EDTF supports two kinds of sets:
271
358
  choice lists (meaning one date out of a list),
272
359
  or inclusive lists.
273
- In EDTF-Ruby, these are covered by the class `EDTF::Set`
274
- and the `choice` attribute.
360
+ In EDTF-Ruby, these are covered by `EDTF::Set` and `EDTF::List`.
275
361
 
276
- > s = EDTF('{1667,1668, 1670..1672}')
277
- > s.choice?
278
- => false
279
- > s.choice!
280
- > s.edtf
281
- => "[1667,1668,1670..1672]"
362
+ s = EDTF('{1667,1668,1670..1672}')
363
+ s.class #-> EDTF::List
364
+ EDTF('[1667,1668,1670..1672]').class #-> EDTF::Set
282
365
 
283
- As you can see above,
284
366
  EDTF-Ruby remembers which parts of the set were specified as a range;
285
367
  ranges are however enumerated for membership tests:
286
368
 
287
- > s.include?(EDTF('1669'))
288
- => false
289
- > s.include?(EDTF('1671'))
290
- => true
369
+ s.include?(EDTF('1669')) #-> false
370
+ s.include?(EDTF('1671')) #-> true
291
371
 
292
372
  Even though we're still aware
293
373
  that the year 1671 is not directly an element of the set:
294
374
 
295
- > s.length
296
- => 3
375
+ s.values.length #-> 3
297
376
 
298
377
  When in doubt, you can always map the set to an array.
299
378
  This will also enumerate all ranges:
300
379
 
301
- > s.map(&:year)
302
- => [1667,1668,1670,1671,1672] # when enumerated there are 5 elements
380
+ s.map(&:year) #-> [1667, 1668, 1670, 1671, 1672]
381
+
382
+ Sets and lists also have an open start or end (`earlier?` and `later?`):
303
383
 
304
- EDTF sets also feature an `#earlier?` and `#later?` attribute:
384
+ s.earlier? #-> false
385
+ s.with(earlier: true).edtf #-> "{..1667,1668,1670..1672}"
305
386
 
306
- > s.earlier?
307
- => false
308
- > s.earlier!
309
- > s.edtf
310
- => "[..1667,1668,1670..1672]"
387
+ Beyond an open start or end,
388
+ every year (or month, or day, like the member there) is included,
389
+ although enumerating the set yields only the members as written,
390
+ like the beginless Ruby range `(..5)` includes 3 but cannot be enumerated:
311
391
 
392
+ EDTF('[..1760]').include?(EDTF('1700')) #-> true
393
+ EDTF('[..1760]').map(&:edtf) #-> ["1760"]
312
394
 
313
- ### Decades and Centuries
314
395
 
315
- The EDTF specification supports so called masked precision strings
316
- to define decades or centuries.
317
- EDTF-Ruby maps these to dedicated intervals
318
- which always cover 10 or 100 years, respectively.
396
+ Decades and centuries
397
+ ---------------------
398
+ Decades and centuries are dedicated periods,
399
+ which always cover 10 or 100 years, respectively:
400
+ the years that begin with the given digits.
319
401
 
320
- > d = EDTF('196x')
321
- > d.edtf
322
- => "196x"
323
- > d.class
324
- => EDTF::Decade
325
- > d.min
326
- => Fri, 01 Jan 1960
327
- > d.max
328
- => Wed, 31 Dec 1969
329
- > d.map(&:year)
330
- => [1960, 1961, 1962, 1963, 1964, 1965, 1966, 1967, 1968, 1969]
402
+ d = EDTF('196')
403
+ d.class #-> EDTF::Decade
404
+ [d.begin.to_s, d.end.to_s] #-> ["1960-01-01", "1969-12-31"]
331
405
 
332
- ### Seasons
406
+ By default, EDTF-Ruby also reads years whose last digits are unspecified
407
+ as decades and centuries (`196X`, `19XX`).
408
+ Decades and centuries are written as they were read;
409
+ new ones are written with unspecified digits,
410
+ or with digits only if `short`:
333
411
 
334
- Finally, EDTF covers seasons.
335
- Again, EDTF-Ruby provides a dedicated class for this.
412
+ EDTF('19XX').class #-> EDTF::Century
413
+ EDTF('19').edtf #-> "19"
414
+ EDTF('19XX').edtf #-> "19XX"
415
+ EDTF::Century.new(19, approximate: true).edtf #-> "19XX~"
416
+ EDTF::Century.new(19, short: true).edtf #-> "19"
417
+
418
+ Both forms are the same century.
419
+ With `centuries: false` (or `strict: true`),
420
+ `19XX` is a year with unspecified digits instead:
421
+
422
+ EDTF.parse('19XX', centuries: false).class #-> EDTF::Date
423
+
424
+
425
+ Seasons
426
+ -------
427
+ Finally, EDTF covers seasons and other divisions of a year
428
+ (ISO 8601-2 codes 21–41),
429
+ and EDTF-Ruby provides a dedicated class for them.
336
430
  Note that EDTF does not make any assumption about the specifics
337
- (which months etc.) of the season
338
- and you don't have to either;
339
- however EDTF-Ruby defines method aliases
340
- which allow you to access the seasons by the names
341
- spring, summer, autumn (or fall), and winter, respectively.
342
- You can also use the more neutral taxonomy of first, second, third, fourth.
343
-
344
- > w = EDTF('2003-24')
345
- > w.winter?
346
- => true
347
- > s = w.succ
348
- > s.spring?
349
- => true
350
- > s.year
351
- => 2004
352
- > s.min
353
- => Mon, 01 Mar 2004
354
- > s.max
355
- => Mon, 31 May 2004
356
- > s.to_a.length
357
- => 92
358
- > w.to_a.length
359
- => 91
360
-
361
- As you can see, spring 2004 lasted one day longer than winter 2003
362
- (note that spring and winter here do not relate to the astronomical seasons
363
- but strictly to three month periods).
364
-
365
- Of course you can print seasons to EDTF strings, too.
366
- Finally, seasons can be uncertain/approximate.
367
-
368
- > s.edtf
369
- => "2004-21"
370
- > s.approximate!.edtf
371
- => "2004-21~"
372
-
373
-
374
- For additional features,
375
- please take a look at the documentation
376
- or the extensive list of rspec examples.
431
+ (which months etc.) of the seasons;
432
+ EDTF-Ruby uses meteorological seasons (three month periods).
433
+
434
+ w = EDTF('2003-24')
435
+ [w.begin.to_s, w.end.to_s] #-> ["2003-12-01", "2004-02-29"]
436
+ s = w.succ
437
+ s.edtf #-> "2004-21"
438
+ (s.end - s.begin).to_i + 1 #-> 92
439
+ (w.end - w.begin).to_i + 1 #-> 91
440
+
441
+ As you can see, spring 2004 lasted one day longer than winter 2003.
442
+ Seasons can be uncertain or approximate, too:
443
+
444
+ s.with(approximate: true).edtf #-> "2004-21~"
445
+
446
+
447
+ Parser
448
+ ------
449
+ To use EDTF-Ruby's parser directly, use `EDTF::Parser`.
450
+ The parser returns frozen hashes
451
+ which you can pass to `EDTF()` for conversion to EDTF objects,
452
+ or to your own post-processing.
453
+
454
+ EDTF::Parser.new.parse('2016-02') #-> {type: :date, values: [2016, 2], level: 0}
455
+
456
+ As you can see, the parse result includes the compatibility level of
457
+ the string parsed;
458
+ the values array contains the individual date parts (months are 1-based).
459
+ Unspecified, uncertain, or approximate digits are returned
460
+ as the numeric value of a bitmask:
461
+
462
+ EDTF::Parser.new.parse('2016?-~02') #-> {type: :date, values: [2016, 2], uncertain: 15, approximate: 48, level: 2}
463
+ EDTF::Parser.new.parse('20XX-02') #-> {type: :date, values: [2000, 2], unspecified: 12, level: 2}
464
+
465
+ Unspecified digits always hold the least possible value,
466
+ e.g., 2000 for 20XX.
467
+ Intervals, sets, and lists contain their parsed constituent dates in
468
+ the values array:
469
+
470
+ EDTF::Parser.new.parse('2015/..')[:values].last #-> :open
471
+
472
+ Parse results are plain data:
473
+ you can store them, e.g. as JSON,
474
+ and `EDTF()` builds objects from them again, also when read back from JSON.
475
+
476
+ ### Parser options
477
+
478
+ By passing options to `EDTF.parse` or `EDTF::Parser.new`,
479
+ you can ensure EDTF-Ruby accepts only dates supported by your application.
480
+
481
+ EDTF.parse('2016?', level: 0) #-> nil
482
+ EDTF.parse('2016?', level: 1) #-> #<EDTF::Date 2016?>
483
+
484
+ EDTF.parse('2016?-02', level: 1) #-> nil
485
+ EDTF.parse('2016?-02', level: 2) #-> #<EDTF::Date 2016?-02>
486
+
487
+ The options are:
488
+
489
+ * `level:` the highest level to accept (0–2, default 2).
490
+ * `extensions:` the non-standard extensions to accept:
491
+ `true` (all), `false` (none),
492
+ or a list of names (`:season_uncertainty`, `:season_intervals`,
493
+ `:basic_offset`);
494
+ by default all but `:season_intervals`.
495
+ * `legacy:` whether to read [legacy syntax][legacy-syntax] (default true).
496
+ * `strict:` ISO 8601-2 only:
497
+ turns off extensions, legacy syntax,
498
+ and reading `19XX` as a century,
499
+ unless you pass those options, too.
500
+ * `max_year_digits:` longer years are rejected (default 100);
501
+ exponents let short strings stand for huge years.
502
+ * `calendar:` the calendar to read dates in:
503
+ `:gregorian` (the default), `:julian`, `:italy`, `:england`,
504
+ or the Julian day of a reform.
505
+ * `year_zero:` `false` to read years before 1 without a year 0
506
+ (`-0001` is 1 BC); they are written the same way again.
507
+ * `centuries:` (`EDTF.parse` only) whether to read `19XX` and `196X`
508
+ as centuries and decades (default true, unless `strict: true`).
509
+
510
+ For example:
511
+
512
+ EDTF.parse('2001-21?', extensions: false) #-> nil
513
+ EDTF.parse('2004/open', strict: true) #-> nil
514
+ EDTF.parse('2004/..', strict: true) #-> #<EDTF::Interval 2004/..>
515
+
516
+
517
+ Rails and ActiveSupport
518
+ -----------------------
519
+ EDTF-Ruby does not depend on ActiveSupport,
520
+ but EDTF dates and date-times inherit from Ruby's Date and Time,
521
+ which ActiveSupport extends.
522
+ With ActiveSupport loaded:
523
+
524
+ * Date and time calculations (`+ 1.month`, `advance`, `beginning_of_day`, …)
525
+ return plain dates and times, like all date math.
526
+ * `to_json` writes the EDTF string of every type.
527
+ * Times in a zone (`ActiveSupport::TimeWithZone`)
528
+ compare with EDTF dates and date-times like Ruby times.
529
+
530
+ EDTF-Ruby no longer loads ActiveSupport itself:
531
+ outside Rails, require it if you use its extensions.
532
+
533
+ To store EDTF values, store their EDTF strings
534
+ and read them back with `EDTF()`;
535
+ a date column would keep only the first day of a period.
536
+
537
+
538
+ Legacy syntax
539
+ -------------
540
+ Earlier versions of EDTF used a draft syntax
541
+ that ISO 8601-2 replaced
542
+ (`?~` became `%`, `u` became `X`, `open` became `..`, …).
543
+ EDTF-Ruby still reads the draft syntax and writes ISO 8601-2;
544
+ enable deprecation warnings to see which input uses it:
545
+
546
+ $ RUBYOPT=-W:deprecated bundle exec rake
547
+ EDTF "2004/open": `open` is legacy syntax, use `..`
548
+
549
+ To audit stored dates, use `EDTF.legacy?`,
550
+ e.g. to print each line of a file that uses legacy syntax:
551
+
552
+ $ ruby -redtf -ne 'print if EDTF.legacy?($_.chomp)' dates.txt
553
+
554
+ To convert stored strings, see [UPGRADING.md][upgrading];
555
+ `legacy: false` (or `strict: true`) turns legacy syntax off.
377
556
 
378
557
 
379
558
  Contributing
380
559
  ------------
381
- The EDTF-Ruby source code is [hosted on GitHub](https://github.com/inukshuk/edtf-ruby).
560
+ The EDTF-Ruby source code is [hosted on GitHub][github].
382
561
  You can check out a copy of the latest code using Git:
383
562
 
384
563
  $ git clone https://github.com/inukshuk/edtf-ruby.git
@@ -389,16 +568,25 @@ To get started, install the dependencies and run all tests:
389
568
  $ bundle install
390
569
  $ bundle exec rake
391
570
 
392
- If you change the grammar in `lib/edtf/parser.y`,
393
- regenerate the parser with `bundle exec rake racc`.
571
+ `rake` runs the specs, the specs with ActiveSupport loaded
572
+ (`rake spec:active_support`, in their own process),
573
+ and the Cucumber features (see [features/README.md][features]).
574
+
575
+ If you change a grammar
576
+ (`lib/edtf/iso.y` or `lib/edtf/legacy.y`),
577
+ regenerate the parsers with `bundle exec rake racc`.
394
578
 
395
579
  If you've found a bug or have a question,
396
580
  please open an issue on the
397
- [EDTF-Ruby issue tracker](https://github.com/inukshuk/edtf-ruby/issues).
581
+ [EDTF-Ruby issue tracker][issues].
398
582
  Or, for extra credit, clone the EDTF-Ruby repository,
399
583
  write a failing example, fix the bug
400
584
  and submit a pull request.
401
585
 
586
+ [github]: https://github.com/inukshuk/edtf-ruby
587
+ [features]: features/README.md
588
+ [issues]: https://github.com/inukshuk/edtf-ruby/issues
589
+
402
590
 
403
591
  Credits
404
592
  -------