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/lib/edtf/iso.y ADDED
@@ -0,0 +1,490 @@
1
+ # -*- racc -*-
2
+ #
3
+ # The ISO 8601-2 grammar: EDTF levels 0 to 2 and EDTF-Ruby's extensions.
4
+ # Section headers give the levels; rules for extensions are marked.
5
+ #
6
+ # Regenerate lib/edtf/iso.rb with `bundle exec rake racc`.
7
+
8
+ class EDTF::ISO < EDTF::Grammar
9
+ token UA MINUS
10
+ expect 0
11
+
12
+ rule
13
+
14
+ edtf
15
+ : date # levels 0-2
16
+ | date_time # level 0
17
+ | interval # levels 0-2
18
+ | year # levels 1-2
19
+ | set # level 2
20
+ ;
21
+
22
+
23
+ # ---- Dates, seasons, decades and centuries ----
24
+
25
+ # A date is made of parts: the year, month and day.
26
+ # Each part may have unspecified digits (X, levels 1-2)
27
+ # and qualifiers on either side (levels 1-2):
28
+ # a qualifier left of a part qualifies only that part,
29
+ # one on its right that part and all parts to its left.
30
+ # A second part from 21 to 41 is a season (levels 1-2);
31
+ # a year of three or two digits is a decade (level 2)
32
+ # or a century (level 0).
33
+ date
34
+ : year_part { result = date_of(val[0]) }
35
+ | year_part '-' part { result = date_of(val[0], val[2]) }
36
+ | year_part '-' part '-' part { result = date_of(val[0], val[2], val[4]) }
37
+ ;
38
+
39
+ year_part
40
+ : ua sign xdigits ua { result = [val[0], val[1] + val[2], val[3]] }
41
+ ;
42
+
43
+ part
44
+ : ua xdigits ua { result = val }
45
+ ;
46
+
47
+ sign
48
+ : /* none */ { result = '' }
49
+ | minus
50
+ ;
51
+
52
+ # The minus sign U+2212 or its ASCII stand-in, the hyphen-minus.
53
+ minus
54
+ : '-'
55
+ | MINUS
56
+ ;
57
+
58
+ ua
59
+ : /* none */ { result = [] }
60
+ | UA
61
+ ;
62
+
63
+ xdigits
64
+ : xdigit
65
+ | xdigits xdigit { result = val[0] + val[1] }
66
+ ;
67
+
68
+ xdigit
69
+ : digit { result = val[0].to_s }
70
+ | 'X'
71
+ ;
72
+
73
+
74
+ # ---- Date-times (level 0) ----
75
+
76
+ date_time
77
+ : date 'T' time {
78
+ result = date_time(val[0], val[2])
79
+ }
80
+ | date 'T' time offset {
81
+ result = date_time(val[0], val[2], val[3])
82
+ }
83
+ ;
84
+
85
+ # Times may stop at the hour or minute (T14, T14:39);
86
+ # fractions of a second are read in milliseconds.
87
+ time
88
+ : hour { result = val }
89
+ | hour ':' minute { result = val.values_at(0, 2) }
90
+ | hour ':' minute ':' second {
91
+ result = val.values_at(0, 2, 4)
92
+ }
93
+ | hour ':' minute ':' second fraction {
94
+ result = val.values_at(0, 2, 4, 5)
95
+ }
96
+ ;
97
+
98
+ fraction
99
+ : decimal_sign digits { result = milliseconds(val[1]) }
100
+ ;
101
+
102
+ decimal_sign
103
+ : '.'
104
+ | ','
105
+ ;
106
+
107
+ digits
108
+ : digit { result = val[0].to_s }
109
+ | digits digit { result = val[0] + val[1].to_s }
110
+ ;
111
+
112
+ hour : d00_23 ;
113
+ minute : d00_59 ;
114
+ second : d00_59 ;
115
+
116
+ # Offsets are written +hh:mm, +hh, or +hhmm (extension: basic-offset).
117
+ offset
118
+ : 'Z' { result = 0 }
119
+ | '+' offset_time { result = offset(1, *val[1]) }
120
+ | minus offset_time { result = offset(-1, *val[1]) }
121
+ ;
122
+
123
+ offset_time
124
+ : hour ':' minute { result = [val[0], val[2]] }
125
+ | hour { result = [val[0], 0] }
126
+ | hour minute {
127
+ extension :basic_offset
128
+ result = [val[0], val[1]]
129
+ }
130
+ ;
131
+
132
+
133
+ # ---- Intervals (levels 0-2) ----
134
+
135
+ # An empty end is unknown, `..` is open.
136
+ interval
137
+ : interval_end '/' interval_end { result = season_interval(val[0], val[2]) }
138
+ | interval_end '/' end_of_day { result = season_interval(val[0], val[2]) }
139
+ ;
140
+
141
+ # 24:00 is the end of a day (ISO 8601-1), but only as an interval's end.
142
+ end_of_day
143
+ : date 'T' midnight { result = date_time(val[0], val[2]) }
144
+ | date 'T' midnight offset { result = date_time(val[0], val[2], val[3]) }
145
+ ;
146
+
147
+ midnight
148
+ : '2' '4' { result = [24] }
149
+ | '2' '4' ':' '0' '0' { result = [24, 0] }
150
+ | '2' '4' ':' '0' '0' ':' '0' '0' { result = [24, 0, 0] }
151
+ ;
152
+
153
+ interval_end
154
+ : /* none */ { result = :unknown }
155
+ | '..' { result = :open }
156
+ | date { result = interval_end(val[0]) }
157
+ | date_time
158
+ ;
159
+
160
+
161
+ # ---- Years with Y or significant digits (levels 1-2) ----
162
+
163
+ # Y marks years with more than four digits (level 1),
164
+ # E an exponent and S significant digits (level 2).
165
+ year
166
+ : 'Y' sign integer {
167
+ result = year(long_year(signed(val[1], val[2])), 1)
168
+ }
169
+ | 'Y' sign integer 'S' integer {
170
+ result = year(long_year(signed(val[1], val[2])), 2, val[4])
171
+ }
172
+ | 'Y' sign integer 'E' integer significant {
173
+ result = year(exponent(signed(val[1], val[2]), val[4]), 2, val[5])
174
+ }
175
+ | date 'S' integer {
176
+ result = significant_year(val[0], val[2])
177
+ }
178
+ ;
179
+
180
+ significant
181
+ : /* none */ { result = nil }
182
+ | 'S' integer { result = val[1] }
183
+ ;
184
+
185
+
186
+ # ---- Sets and lists (level 2) ----
187
+
188
+ set
189
+ : '[' list ']' { result = { type: :set, **val[1] } }
190
+ | '{' list '}' { result = { type: :list, **val[1] } }
191
+ ;
192
+
193
+ list
194
+ : members { result = list(*val[0]) }
195
+ | members ',' later { result = list(*val[0], val[2], later: true) }
196
+ | later { result = list(val[0], later: true) }
197
+ | earlier { result = list(val[0], earlier: true) }
198
+ | earlier ',' members { result = list(val[0], *val[2], earlier: true) }
199
+ | earlier ',' later {
200
+ result = list(val[0], val[2], earlier: true, later: true)
201
+ }
202
+ | earlier ',' members ',' later {
203
+ result = list(val[0], *val[2], val[4], earlier: true, later: true)
204
+ }
205
+ ;
206
+
207
+ members
208
+ : member { result = [val[0]] }
209
+ | members ',' member { result = val[0] + [val[2]] }
210
+ ;
211
+
212
+ member
213
+ : date { result = member(val[0]) }
214
+ | consecutives
215
+ ;
216
+
217
+ # Open ends and consecutive dates are plain dates.
218
+ earlier
219
+ : '..' date { result = plain(val[1]) }
220
+ ;
221
+
222
+ later
223
+ : date '..' { result = plain(val[0]) }
224
+ ;
225
+
226
+ consecutives
227
+ : date '..' date { result = consecutives(val[0], val[2]) }
228
+ ;
229
+
230
+
231
+ # ---- Digits ----
232
+
233
+ integer
234
+ : positive_digit
235
+ | integer digit { result = 10 * val[0] + val[1] }
236
+ ;
237
+
238
+ digit
239
+ : '0'
240
+ | positive_digit
241
+ ;
242
+
243
+ positive_digit
244
+ : '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
245
+ ;
246
+
247
+ d00_23
248
+ : '0' digit { result = val[1] }
249
+ | '1' digit { result = 10 + val[1] }
250
+ | '2' d0_3 { result = 20 + val[1] }
251
+ ;
252
+
253
+ d00_59
254
+ : d0_5 digit { result = 10 * val[0] + val[1] }
255
+ ;
256
+
257
+ d0_3 : '0' | '1' | '2' | '3' ;
258
+ d0_5 : d0_3 | '4' | '5' ;
259
+
260
+ end
261
+
262
+ ---- inner
263
+
264
+ QUALIFIERS = {
265
+ '?' => [:uncertain],
266
+ '~' => [:approximate],
267
+ '%' => [:uncertain, :approximate]
268
+ }.freeze
269
+
270
+ # Digits are tokens with their value, qualifiers UA tokens;
271
+ # every other character is a token of its own.
272
+ # Characters the grammar does not know are syntax errors.
273
+ def next_token
274
+ case
275
+ when @src.eos?
276
+ nil
277
+ when @src.scan(/\d/)
278
+ [@src.matched, @src.matched.to_i]
279
+ when @src.scan(/[?~%]/)
280
+ [:UA, QUALIFIERS[@src.matched]]
281
+ when @src.scan(/\u2212/)
282
+ [:MINUS, '-']
283
+ when @src.scan(/\.\.|./m)
284
+ [@src.matched, @src.matched]
285
+ end
286
+ end
287
+
288
+ PART_NAMES = %i[year month day].freeze
289
+
290
+ # Builds a date, season, decade or century from its parts,
291
+ # each [left qualifiers, digits with X, right qualifiers].
292
+ def date_of(*parts)
293
+ digits = parts.map { |part| part[1] }
294
+ negative = digits[0].start_with?('-')
295
+ digits[0] = digits[0].delete_prefix('-')
296
+ raw = digits.map { |d| d.tr('X', '0').to_i }
297
+
298
+ if negative && raw[0].zero? && !digits[0].include?('X')
299
+ raise ParseError, "invalid year -#{digits[0]}, use #{digits[0]}"
300
+ end
301
+
302
+ case digits.map(&:length)
303
+ when [2], [3]
304
+ raise ArgumentError, 'decades and centuries are not negative' if negative
305
+ left, _, right = parts[0]
306
+ epoch(raw[0], digits[0], left | right)
307
+ when [4, 2]
308
+ if raw[1] > 12 && !digits[1].include?('X')
309
+ season_of(negative, raw[0], raw[1], parts)
310
+ else
311
+ calendar_date(negative, digits, raw, parts)
312
+ end
313
+ when [4], [4, 2, 2]
314
+ calendar_date(negative, digits, raw, parts)
315
+ else
316
+ raise ParseError, "invalid date #{digits.join('-')}"
317
+ end
318
+ end
319
+
320
+ def calendar_date(negative, digits, raw, parts)
321
+ mask = Bitmask.compute(digits.join.ljust(8, '0'))
322
+ values = mask.zero? ? raw : Bitmask.new(mask).min(raw)
323
+ year, month, day = values
324
+
325
+ if month && !fits?(digits[1], 1..12)
326
+ raise ArgumentError, "invalid month #{digits[1]}"
327
+ end
328
+
329
+ if day
330
+ unless fits?(digits[2], 1..31)
331
+ raise ArgumentError, "invalid day #{digits[2]}"
332
+ end
333
+
334
+ check_day(*values)
335
+ end
336
+
337
+ year = Bitmask.new(mask).least_year(year) if negative && year.zero?
338
+ values[0] = -year if negative
339
+ result = date(*values)
340
+ result[:unspecified] = mask unless mask.zero?
341
+
342
+ parts.each_with_index do |(left, _, right), i|
343
+ qualify(result, left, PART_NAMES[i])
344
+ qualify(result, right, PART_NAMES[0..i])
345
+ end
346
+
347
+ # Level 1 qualifies only at the end (2001?); ?2001 is level 2.
348
+ result[:level] = 2 if parts.any? { |left, _, _| left.any? }
349
+ result
350
+ end
351
+
352
+ # Returns true if a number in range can be written with digits,
353
+ # where X stands for any digit.
354
+ def fits?(digits, range)
355
+ pattern = Regexp.new(digits.gsub('X') { '\\d' })
356
+ range.any? { |n| pattern.match?(format('%02d', n)) }
357
+ end
358
+
359
+ def epoch(value, digits, qualifiers)
360
+ raise ArgumentError, "invalid year #{digits}" if digits.include?('X')
361
+ type = digits.length == 2 ? :century : :decade
362
+ qualify({ type: type, values: [value] }, qualifiers)
363
+ end
364
+
365
+ # Seasons 21-24 are level 1, 25-41 level 2.
366
+ # Qualified seasons and seasons with unspecified year digits
367
+ # are an extension (season-uncertainty, from edtf.js).
368
+ def season_of(negative, year, number, parts)
369
+ unless (21..41).cover?(number)
370
+ raise ArgumentError, "invalid month or season #{number}"
371
+ end
372
+
373
+ mask = Bitmask.compute(parts[0][1].delete_prefix('-').ljust(8, '0'))
374
+ year = Bitmask.new(mask).least_year(year) if negative && year.zero?
375
+ result = { type: :season, values: [negative ? -year : year, number] }
376
+
377
+ parts.each_with_index do |(left, _, right), i|
378
+ qualify(result, left, PART_NAMES[i])
379
+ qualify(result, right, PART_NAMES[0..i])
380
+ end
381
+
382
+ qualified = result.key?(:uncertain) || result.key?(:approximate)
383
+ extension :season_uncertainty if qualified || !mask.zero?
384
+ return result if mask.zero?
385
+
386
+ raise ArgumentError, 'unspecified digits cannot be qualified' if qualified
387
+ result.merge(unspecified: mask)
388
+ end
389
+
390
+ # Seasons are interval ends as an extension (season-intervals, from edtf.js),
391
+ # checked by season_interval.
392
+ def interval_end(result)
393
+ result[:type] == :season ? result : member(result)
394
+ end
395
+
396
+ # Season intervals go from season to season.
397
+ def season_interval(from, to)
398
+ seasons = [from, to].map { |value| value.is_a?(Hash) && value[:type] == :season }
399
+
400
+ if seasons.any?
401
+ raise ArgumentError, 'invalid season in an interval' unless seasons.all?
402
+ extension :season_intervals
403
+ end
404
+
405
+ interval(from, to)
406
+ end
407
+
408
+ # Interval ends and set members are dates, decades or centuries.
409
+ def member(result)
410
+ return result unless result[:type] == :season
411
+ raise ArgumentError, 'invalid season in an interval or set'
412
+ end
413
+
414
+ def plain(result)
415
+ if result[:type] != :date || result.keys != %i[type values]
416
+ raise ArgumentError, 'open ends and consecutive dates must be plain dates'
417
+ end
418
+
419
+ result
420
+ end
421
+
422
+ def consecutives(from, to)
423
+ unless plain(from)[:values].length == plain(to)[:values].length
424
+ raise ArgumentError, 'consecutive dates must have the same precision'
425
+ end
426
+
427
+ [from, to]
428
+ end
429
+
430
+ # Date-times have a plain, complete date.
431
+ def date_time(date, time, offset = nil)
432
+ if date.keys != %i[type values] || date[:values].length != 3
433
+ raise ParseError, 'a date-time needs a complete date'
434
+ end
435
+
436
+ result = { type: :date_time, values: [*date[:values], *time] }
437
+ result[:offset] = offset unless offset.nil?
438
+ result
439
+ end
440
+
441
+ # Returns the offset in minutes.
442
+ # ISO sets no range: hours run to 23 and minutes to 59
443
+ # (historical local times exceed today's zones).
444
+ # Zero is written +00:00; -00:00 is invalid.
445
+ def offset(sign, hours, minutes)
446
+ offset = 60 * hours + minutes
447
+
448
+ if sign < 0 && offset.zero?
449
+ sign = sign < 0 ? '-' : '+'
450
+ raise ArgumentError,
451
+ format('invalid offset %s%02d:%02d', sign, hours, minutes)
452
+ end
453
+
454
+ sign * offset
455
+ end
456
+
457
+ def milliseconds(digits)
458
+ if digits.length > 3
459
+ raise ArgumentError, "too many fraction digits: #{digits}, at most 3"
460
+ end
461
+
462
+ digits.ljust(3, '0').to_i
463
+ end
464
+
465
+ def signed(sign, number)
466
+ sign.empty? ? number : -number
467
+ end
468
+
469
+ # Years with fewer than five digits are written without Y.
470
+ def long_year(year)
471
+ if year.abs < 10000
472
+ raise ParseError, "invalid year Y#{year}, use #{year}"
473
+ end
474
+
475
+ year
476
+ end
477
+
478
+ # Four-digit years with significant digits, e.g. 1950S2.
479
+ def significant_year(date, significant)
480
+ if date[:type] != :date || date.keys != %i[type values] ||
481
+ date[:values].length != 1
482
+ raise ArgumentError, 'only years can have significant digits'
483
+ end
484
+
485
+ year(date[:values][0], 2, significant)
486
+ end
487
+
488
+ def list(*values, **open)
489
+ { values: values, **open }
490
+ end