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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +40 -0
- data/README.md +448 -260
- data/UPGRADING.md +227 -0
- data/lib/edtf/bitmask.rb +277 -0
- data/lib/edtf/builder.rb +177 -0
- data/lib/edtf/date.rb +435 -284
- data/lib/edtf/date_time.rb +285 -11
- data/lib/edtf/epoch.rb +107 -67
- data/lib/edtf/grammar.rb +118 -0
- data/lib/edtf/interval.rb +124 -254
- data/lib/edtf/iso.rb +1136 -0
- data/lib/edtf/iso.y +490 -0
- data/lib/edtf/legacy.rb +1888 -0
- data/lib/edtf/legacy.y +625 -0
- data/lib/edtf/parser.rb +249 -1985
- data/lib/edtf/period.rb +199 -0
- data/lib/edtf/season.rb +160 -146
- data/lib/edtf/set.rb +180 -56
- data/lib/edtf/version.rb +1 -1
- data/lib/edtf.rb +43 -30
- metadata +15 -28
- data/lib/edtf/compatibility.rb +0 -6
- data/lib/edtf/extensions.rb +0 -11
- data/lib/edtf/parser.y +0 -666
- data/lib/edtf/uncertainty.rb +0 -100
- data/lib/edtf/unknown.rb +0 -25
data/UPGRADING.md
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
Upgrading to EDTF-Ruby 5.0
|
|
2
|
+
==========================
|
|
3
|
+
EDTF-Ruby 5.0 switches from the EDTF draft syntax to ISO 8601-2.
|
|
4
|
+
It still reads the draft syntax (legacy syntax, see below),
|
|
5
|
+
but writes ISO 8601-2 only.
|
|
6
|
+
|
|
7
|
+
* **No core patches.**
|
|
8
|
+
EDTF-Ruby 4.x extended Ruby's `Date`, `DateTime`, and `Range`.
|
|
9
|
+
5.0 has its own types instead;
|
|
10
|
+
`EDTF::Date` is still a Ruby `Date`,
|
|
11
|
+
and `EDTF::DateTime` is now a Ruby `Time`.
|
|
12
|
+
The only addition to Ruby is the conversion method `EDTF()`.
|
|
13
|
+
* **Immutable values.**
|
|
14
|
+
All EDTF objects are frozen;
|
|
15
|
+
instead of the bang! methods, `with` returns a modified copy.
|
|
16
|
+
* **Periods.**
|
|
17
|
+
Every EDTF type stands for *a period of time*
|
|
18
|
+
with plain Ruby dates as `begin` and `end`,
|
|
19
|
+
and the same `cover?`, `===`, `<=>` and `edtf`.
|
|
20
|
+
As for Ruby ranges, `cover?` (and `===`) test the bounds.
|
|
21
|
+
`include?`, like `Range#include?`, tests membership,
|
|
22
|
+
for intervals, sets, and lists.
|
|
23
|
+
* **No ActiveSupport.**
|
|
24
|
+
EDTF-Ruby no longer depends on or loads ActiveSupport,
|
|
25
|
+
but works fine alongside it.
|
|
26
|
+
|
|
27
|
+
If you parse ISO strings and print them,
|
|
28
|
+
replacing `Date.edtf` is likely all you need.
|
|
29
|
+
EDTF-Ruby 4.1 helps you prepare:
|
|
30
|
+
it warns about legacy syntax and deprecated calls
|
|
31
|
+
when deprecation warnings are enabled
|
|
32
|
+
(`RUBYOPT=-W:deprecated`, or `Warning[:deprecated] = true`),
|
|
33
|
+
and `EDTF.legacy?` finds stored strings in legacy syntax.
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
Parsing and printing
|
|
37
|
+
--------------------
|
|
38
|
+
| 4.x | 5.0 |
|
|
39
|
+
|-------------------------------|------------------------------------------|
|
|
40
|
+
| `Date.edtf(s)` | `EDTF.parse(s)` |
|
|
41
|
+
| `Date.edtf!(s)` | `EDTF.parse!(s)` or `EDTF(s)` |
|
|
42
|
+
| `date.edtf` on a plain `Date` | `EDTF(date).edtf` |
|
|
43
|
+
| `range.edtf` | `EDTF::Interval.new(a, b).edtf` |
|
|
44
|
+
| `EDTF::Parser#parse` | returns hashes; `EDTF(hash)` builds them |
|
|
45
|
+
|
|
46
|
+
Output is ISO 8601-2:
|
|
47
|
+
|
|
48
|
+
| 4.x | 5.0 |
|
|
49
|
+
|--------------------------------|----------------------------------------|
|
|
50
|
+
| `1984?~` | `1984%` |
|
|
51
|
+
| `2004-(06)?-11` | `2004-?06-11` |
|
|
52
|
+
| `unknown/2006`, `2004/unknown` | `/2006`, `2004/` |
|
|
53
|
+
| `2004/open` | `2004/..` |
|
|
54
|
+
| `199u` | `199X` |
|
|
55
|
+
| `19xx`, `196x` | `19XX`, `196X` |
|
|
56
|
+
| `y17e7` | `Y170000000` |
|
|
57
|
+
| `{1960, 1961-12}` | `{1960,1961-12}` |
|
|
58
|
+
| `2004-01-01T10:10:10+00:00` | `2004-01-01T10:10:10Z` |
|
|
59
|
+
| `2001-21^southern` | `2001-29` (a hemisphere season) |
|
|
60
|
+
| `2001-02-03^julian` | `2001-02-03` (a Julian date) |
|
|
61
|
+
| `2003-23^european` | `2003-23` (no other season qualifiers) |
|
|
62
|
+
|
|
63
|
+
`to_s` returns the EDTF string, too, for every type;
|
|
64
|
+
`iso8601` still returns the ISO 8601-1 string
|
|
65
|
+
of the first day (or of the instant, for date-times).
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
Migrating stored strings
|
|
69
|
+
------------------------
|
|
70
|
+
5.0 reads legacy syntax by default and writes ISO 8601-2,
|
|
71
|
+
so `EDTF(string).edtf` converts a stored string:
|
|
72
|
+
|
|
73
|
+
EDTF('2004-(06)?-11').edtf #-> "2004-?06-11"
|
|
74
|
+
EDTF('2001-21^southern').edtf #-> "2001-29"
|
|
75
|
+
|
|
76
|
+
`EDTF.legacy?` finds the strings that need it.
|
|
77
|
+
Season qualifiers other than hemispheres (`^european`)
|
|
78
|
+
have no ISO 8601-2 equivalent and are dropped;
|
|
79
|
+
`EDTF::Parser` results still record them (`qualifier:`).
|
|
80
|
+
Calendars are kept (`^julian` reads a Julian date),
|
|
81
|
+
but ISO 8601-2 strings do not name them:
|
|
82
|
+
read the converted strings with `EDTF.parse(s, calendar: :julian)`.
|
|
83
|
+
Unknown calendars (`^xyz`) raise an `ArgumentError`.
|
|
84
|
+
With deprecation warnings enabled (`Warning[:deprecated] = true`),
|
|
85
|
+
each conversion names the legacy syntax it read.
|
|
86
|
+
Reversed intervals (`2008/2004`) raise an `ArgumentError`
|
|
87
|
+
and need fixing by hand:
|
|
88
|
+
|
|
89
|
+
strings.each do |s|
|
|
90
|
+
iso = EDTF(s).edtf
|
|
91
|
+
puts "#{s} -> #{iso}" unless iso == s
|
|
92
|
+
rescue ArgumentError => e
|
|
93
|
+
puts "#{s}: #{e.message}"
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
`EDTF.parse(s, legacy: false)` (or `strict: true`) reads ISO 8601-2 only.
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
Dates
|
|
100
|
+
-----
|
|
101
|
+
| 4.x | 5.0 |
|
|
102
|
+
|----------------------------------|--------------------------------------|
|
|
103
|
+
| `d.precision = :month` | `d = d.with(precision: :month)` |
|
|
104
|
+
| `d.month_precision!` | `d = d.with(precision: :month)` |
|
|
105
|
+
| `d.month_precision` | `d.with(precision: :month)` |
|
|
106
|
+
| `d.uncertain!(:year)` | `d.with(uncertain: :year)` |
|
|
107
|
+
| `d.approximate!` | `d.with(approximate: true)` |
|
|
108
|
+
| `d.certain!` | `d.with(uncertain: nil)` |
|
|
109
|
+
| `d.precise!` | `d.with(approximate: nil)` |
|
|
110
|
+
| `d.unspecified!(:day)` | `d.with(unspecified: :day)` |
|
|
111
|
+
| `d.uncertain` etc. (structs) | an `EDTF::Bitmask` each |
|
|
112
|
+
| `d.next(3)` (an array) | `(1..3).map { d.succ(_1) }` |
|
|
113
|
+
| `d.change`, `d.advance` | return plain dates now |
|
|
114
|
+
| `d.calendar` (a String) | `d.calendar` (a Symbol: `:julian`) |
|
|
115
|
+
| `EDTF::Unknown` (`uuuu`, `XXXX`) | `EDTF::Date`, unspecified year |
|
|
116
|
+
| `Date.today` with EDTF methods | `EDTF(Date.today)` |
|
|
117
|
+
|
|
118
|
+
`d.succ(3)` is the third successor.
|
|
119
|
+
`EDTF::Date.today` and Ruby's other constructors are private.
|
|
120
|
+
|
|
121
|
+
`with` also replaces `year`, `month`, and `day`;
|
|
122
|
+
values beyond the precision raise
|
|
123
|
+
(`EDTF('2016').with(month: 3)` needs `precision: :month`).
|
|
124
|
+
It replaces values instead of adding to them:
|
|
125
|
+
`d.with(uncertain: :year)` means only the year is uncertain.
|
|
126
|
+
To add a part, combine the bitmasks:
|
|
127
|
+
`d.with(uncertain: d.uncertain | :year)`.
|
|
128
|
+
|
|
129
|
+
Plain Ruby dates have no EDTF methods any more;
|
|
130
|
+
convert them with `EDTF(date)`.
|
|
131
|
+
It keeps the calendar of days before its reform:
|
|
132
|
+
`EDTF(Date.new(1500, 1, 1))` is in Ruby's default calendar, `:italy`.
|
|
133
|
+
Note that `Date.new(1984) == EDTF('1984')` is true,
|
|
134
|
+
because Ruby's `Date#==` compares the day,
|
|
135
|
+
while `EDTF('1984') == Date.new(1984)` is false:
|
|
136
|
+
a year is not the same period as its first day.
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
Date-times
|
|
140
|
+
----------
|
|
141
|
+
| 4.x | 5.0 |
|
|
142
|
+
|--------------------------------|---------------------------------------|
|
|
143
|
+
| a `DateTime` with EDTF methods | `EDTF::DateTime`, a Ruby `Time` |
|
|
144
|
+
| `skip_timezone?` | `floating?` (no offset in the string) |
|
|
145
|
+
| `DateTime.now` | `EDTF(Time.now)` |
|
|
146
|
+
|
|
147
|
+
Ruby's constructors are private, as for dates.
|
|
148
|
+
A date-time without an offset is floating:
|
|
149
|
+
EDTF-Ruby keeps it on the UTC clock, never in the system's time zone.
|
|
150
|
+
EDTF date-times are frozen,
|
|
151
|
+
so `utc` and `localtime` raise; use `getutc` and `getlocal`.
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
Intervals
|
|
155
|
+
---------
|
|
156
|
+
| 4.x | 5.0 |
|
|
157
|
+
|------------------------------------|----------------------------------------|
|
|
158
|
+
| `min`, `max` | `begin`, `end`: dates, nil without one |
|
|
159
|
+
| `length` | `count` |
|
|
160
|
+
| `step(n)` | `each_slice(n)` |
|
|
161
|
+
| `open_end?`, `unknown_start?`, … | `to == :open`, `from == :unknown`, … |
|
|
162
|
+
| `<=>` was 0 for covered dates | periods compare; use `cover?` |
|
|
163
|
+
| `each` yielded the qualified start | yields the start's units, unqualified |
|
|
164
|
+
| open/unknown ends did not iterate | iterate endlessly (`to_a` raises) |
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
Sets
|
|
168
|
+
----
|
|
169
|
+
| 4.x | 5.0 |
|
|
170
|
+
|----------------------------|---------------------------------------------|
|
|
171
|
+
| `EDTF::Set` with `choice?` | `EDTF::Set` (`[…]`) or `EDTF::List` (`{…}`) |
|
|
172
|
+
| `choice!` | `EDTF::Set.new(*list.values)` |
|
|
173
|
+
| `earlier!`, `later!` | `with(earlier: true)`, `with(later: true)` |
|
|
174
|
+
| `set << date` | `set.with(values: set.values + [date])` |
|
|
175
|
+
|
|
176
|
+
An `EDTF::Set` is one of its members, an `EDTF::List` all of them.
|
|
177
|
+
Neither is a Ruby `Set`;
|
|
178
|
+
`to_set` returns one with all members, ranges enumerated.
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
Decades, centuries, and seasons
|
|
182
|
+
-------------------------------
|
|
183
|
+
| 4.x | 5.0 |
|
|
184
|
+
|-------------------------------------|--------------------------------------|
|
|
185
|
+
| `EDTF::Decade.new(1999)` (any year) | `EDTF::Decade.new(199)` (the digits) |
|
|
186
|
+
| `EDTF::Century.new(1999)` | `EDTF::Century.new(19)` |
|
|
187
|
+
| `min`, `max`, `.current` | `begin`, `end`; no `.current` |
|
|
188
|
+
| `EDTF::Season.new(2004, :summer)` | `EDTF::Season.new(2004, 22)` |
|
|
189
|
+
| `season.summer?` | `season.season == 22` |
|
|
190
|
+
| `season.season` (a Symbol) | `season.season` (21–41) |
|
|
191
|
+
| `season.qualifier` | hemisphere seasons (`2001-29`) |
|
|
192
|
+
| `19XX`, `196X` were years | a century, a decade |
|
|
193
|
+
|
|
194
|
+
`EDTF.parse(s, centuries: false)` reads `19XX` and `196X` as years.
|
|
195
|
+
|
|
196
|
+
`EDTF::Parser` results keep season qualifiers (`qualifier:`).
|
|
197
|
+
Seasons 21–24 still span three months, meteorologically
|
|
198
|
+
(winter reaches into the next year).
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
Equality
|
|
202
|
+
--------
|
|
203
|
+
`==` means the same period:
|
|
204
|
+
the same bounds and precision, ignoring qualifiers
|
|
205
|
+
(`EDTF('1906') == EDTF('1906?')`).
|
|
206
|
+
`eql?` and `hash` compare the EDTF expression,
|
|
207
|
+
so qualified values stay apart as hash keys,
|
|
208
|
+
like `1 == 1.0` but not `1.eql?(1.0)` in Ruby.
|
|
209
|
+
|
|
210
|
+
`==` also crosses types:
|
|
211
|
+
a set and a list of the same years,
|
|
212
|
+
or an interval from and to the same year and that year,
|
|
213
|
+
are the same period
|
|
214
|
+
(`EDTF('[2004,2005]') == EDTF('{2004,2005}')`,
|
|
215
|
+
`EDTF('2004/2004') == EDTF('2004')`).
|
|
216
|
+
|
|
217
|
+
Ruby's own `Date#eql?` compares days only,
|
|
218
|
+
so `Date.new(1966, 1, 1).eql?(EDTF('1966'))` is true
|
|
219
|
+
while `EDTF('1966').eql?(Date.new(1966, 1, 1))` is false;
|
|
220
|
+
use EDTF objects on the left, or convert with `EDTF()`.
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
ActiveSupport
|
|
224
|
+
-------------
|
|
225
|
+
EDTF-Ruby 4.x loaded ActiveSupport's date and time extensions.
|
|
226
|
+
5.0 does not:
|
|
227
|
+
outside Rails, require ActiveSupport yourself if you use them.
|
data/lib/edtf/bitmask.rb
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
module EDTF
|
|
2
|
+
|
|
3
|
+
# Bitmasks mark the uncertain, approximate or unspecified
|
|
4
|
+
# digits of a date. Each bit stands for one digit:
|
|
5
|
+
#
|
|
6
|
+
# YYYYMMDD
|
|
7
|
+
# --------
|
|
8
|
+
# Day 00000011
|
|
9
|
+
# Month 00001100
|
|
10
|
+
# Year 11110000
|
|
11
|
+
#
|
|
12
|
+
# Bitmasks are immutable: combining or qualifying returns a new one.
|
|
13
|
+
class Bitmask < Data.define(:value)
|
|
14
|
+
|
|
15
|
+
DIGIT = /\A[xX]\z/
|
|
16
|
+
PATTERN = /\A[0-9xXdDmMyY]{8}\z/
|
|
17
|
+
MAXDAYS = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
|
|
18
|
+
|
|
19
|
+
class << self
|
|
20
|
+
def compute(pattern)
|
|
21
|
+
pattern.each_char.with_index.sum { |c, idx|
|
|
22
|
+
DIGIT.match?(c) ? 2**idx : 0
|
|
23
|
+
}
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def convert(value)
|
|
27
|
+
case value
|
|
28
|
+
when Bitmask
|
|
29
|
+
value.value
|
|
30
|
+
when Integer
|
|
31
|
+
value
|
|
32
|
+
when true
|
|
33
|
+
YMD
|
|
34
|
+
when false, nil
|
|
35
|
+
0
|
|
36
|
+
when Array
|
|
37
|
+
value.sum { |part| convert(part) }
|
|
38
|
+
when Symbol, String
|
|
39
|
+
case value.to_s
|
|
40
|
+
when /\Adays?\z/i
|
|
41
|
+
DAY
|
|
42
|
+
when /\Amonths?\z/i, /\Aseasons?\z/i
|
|
43
|
+
MONTH
|
|
44
|
+
when /\Ayears?\z/i
|
|
45
|
+
YEAR
|
|
46
|
+
when PATTERN
|
|
47
|
+
compute(value.to_s)
|
|
48
|
+
else
|
|
49
|
+
raise ArgumentError, "invalid bitmask: #{value.inspect}"
|
|
50
|
+
end
|
|
51
|
+
else
|
|
52
|
+
raise ArgumentError, "invalid bitmask: #{value.inspect}"
|
|
53
|
+
end
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# Returns the values of a mask like "XXXX05XX",
|
|
57
|
+
# with each X replaced by digit.
|
|
58
|
+
def values(mask, digit: 0, normalize: true)
|
|
59
|
+
num = mask.gsub(/[xX]/, digit.to_s)
|
|
60
|
+
digits = num.match(/\A(\d{4})(\d\d)?(\d\d)?\z/).captures
|
|
61
|
+
values = digits.compact.map(&:to_i)
|
|
62
|
+
normalize ? normalize(values) : values
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
def normalize(values)
|
|
66
|
+
year, month, day = values
|
|
67
|
+
return [year] if month.nil?
|
|
68
|
+
|
|
69
|
+
month = month.clamp(1, 12)
|
|
70
|
+
return [year, month] if day.nil?
|
|
71
|
+
|
|
72
|
+
[year, month, day.clamp(1, MAXDAYS[month - 1])]
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
DAY = compute('yyyymmxx')
|
|
77
|
+
MONTH = compute('yyyyxxdd')
|
|
78
|
+
YEAR = compute('xxxxmmdd')
|
|
79
|
+
|
|
80
|
+
MD = MONTH | DAY
|
|
81
|
+
YM = YEAR | MONTH
|
|
82
|
+
YMD = YEAR | MD
|
|
83
|
+
|
|
84
|
+
YYXX = compute('yyxxmmdd')
|
|
85
|
+
YYYX = compute('yyyxmmdd')
|
|
86
|
+
XXXX = compute('xxxxmmdd')
|
|
87
|
+
|
|
88
|
+
DX = compute('yyyymmdx')
|
|
89
|
+
XD = compute('yyyymmxd')
|
|
90
|
+
MX = compute('yyyymxdd')
|
|
91
|
+
XM = compute('yyyyxmdd')
|
|
92
|
+
|
|
93
|
+
# Maps each qualifier position to the parts it qualifies:
|
|
94
|
+
#
|
|
95
|
+
# ~YYYY~-~MM~-~DD~
|
|
96
|
+
# 0 1 2 3 4 5
|
|
97
|
+
UA = [YEAR, YEAR, MONTH, YM, DAY, YMD].freeze
|
|
98
|
+
|
|
99
|
+
def initialize(value: 0)
|
|
100
|
+
super(value: self.class.convert(value))
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
def to_i
|
|
104
|
+
value
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
def zero?
|
|
108
|
+
value.zero?
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
def intersect?(other)
|
|
112
|
+
(value & self.class.convert(other)) != 0
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
def year?
|
|
116
|
+
intersect?(YEAR)
|
|
117
|
+
end
|
|
118
|
+
|
|
119
|
+
def month?
|
|
120
|
+
intersect?(MONTH)
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
def day?
|
|
124
|
+
intersect?(DAY)
|
|
125
|
+
end
|
|
126
|
+
|
|
127
|
+
def |(other)
|
|
128
|
+
with(value: value | self.class.convert(other))
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
# Returns a copy that also qualifies the parts
|
|
132
|
+
# at the given qualifier position (see UA).
|
|
133
|
+
def qualify(idx)
|
|
134
|
+
self | UA[idx]
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
def qualified?(idx)
|
|
138
|
+
case idx
|
|
139
|
+
when 1
|
|
140
|
+
value == YEAR || (value & YEAR != 0 && value & MONTH == 0)
|
|
141
|
+
when 2
|
|
142
|
+
value == MONTH || (value & MONTH != 0 && value & YEAR == 0)
|
|
143
|
+
when 3
|
|
144
|
+
value == YM
|
|
145
|
+
when 4
|
|
146
|
+
value == DAY || (value & DAY != 0 && value != YMD)
|
|
147
|
+
when 5
|
|
148
|
+
value == YMD
|
|
149
|
+
else
|
|
150
|
+
false
|
|
151
|
+
end
|
|
152
|
+
end
|
|
153
|
+
|
|
154
|
+
# Masks digit strings, e.g. ["2016", "05"] -> ["201X", "05"].
|
|
155
|
+
def masks(values, symbol = 'X')
|
|
156
|
+
offset = 0
|
|
157
|
+
|
|
158
|
+
values.map do |string|
|
|
159
|
+
masked = string.each_char.with_index.map do |c, idx|
|
|
160
|
+
value[offset + idx] == 1 ? symbol : c
|
|
161
|
+
end
|
|
162
|
+
offset += string.length
|
|
163
|
+
masked.join
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
# Adds qualifier symbols, e.g. ["2016", "05"] -> ["2016", "05?"].
|
|
168
|
+
def marks(values, symbol = '?')
|
|
169
|
+
values.each_with_index.map do |string, idx|
|
|
170
|
+
[
|
|
171
|
+
qualified?(idx * 2) ? symbol : '',
|
|
172
|
+
string,
|
|
173
|
+
qualified?(idx * 2 + 1) ? symbol : ''
|
|
174
|
+
].join
|
|
175
|
+
end
|
|
176
|
+
end
|
|
177
|
+
|
|
178
|
+
# The highest values the unspecified digits allow.
|
|
179
|
+
# The year must not be negative; callers handle the sign.
|
|
180
|
+
# Leap years follow the calendar (a Ruby Date start).
|
|
181
|
+
def max(values, start = ::Date::GREGORIAN)
|
|
182
|
+
year, month, day = values
|
|
183
|
+
return [] if year.nil?
|
|
184
|
+
|
|
185
|
+
year = fill(year, '9') if year?
|
|
186
|
+
month = months(year, month, day, start).last if month && month?
|
|
187
|
+
return [year] if month.nil?
|
|
188
|
+
return [year, month] if day.nil?
|
|
189
|
+
|
|
190
|
+
maxdays = MAXDAYS[month - 1]
|
|
191
|
+
leap = ::Date.valid_date?(year, 2, 29, start)
|
|
192
|
+
|
|
193
|
+
case value & DAY
|
|
194
|
+
when DAY
|
|
195
|
+
day = maxdays
|
|
196
|
+
when DX
|
|
197
|
+
day = [maxdays, day + (9 - day % 10)].min
|
|
198
|
+
when XD
|
|
199
|
+
day %= 10
|
|
200
|
+
|
|
201
|
+
if month == 2
|
|
202
|
+
day += (day == 9 && !leap) ? 10 : 20
|
|
203
|
+
else
|
|
204
|
+
day += day < 2 ? 30 : 20
|
|
205
|
+
day -= 10 if day > maxdays
|
|
206
|
+
end
|
|
207
|
+
end
|
|
208
|
+
|
|
209
|
+
day = 28 if month == 2 && day > 28 && !leap
|
|
210
|
+
|
|
211
|
+
[year, month, day]
|
|
212
|
+
end
|
|
213
|
+
|
|
214
|
+
# The lowest values the unspecified digits allow.
|
|
215
|
+
# The year must not be negative; callers handle the sign.
|
|
216
|
+
# Leap years follow the calendar (a Ruby Date start).
|
|
217
|
+
def min(values, start = ::Date::GREGORIAN)
|
|
218
|
+
year, month, day = values
|
|
219
|
+
return [] if year.nil?
|
|
220
|
+
|
|
221
|
+
year = fill(year, '0') if year?
|
|
222
|
+
month = months(year, month, day, start).first if month && month?
|
|
223
|
+
return [year] if month.nil?
|
|
224
|
+
return [year, month] if day.nil?
|
|
225
|
+
|
|
226
|
+
case value & DAY
|
|
227
|
+
when DAY
|
|
228
|
+
day = 1
|
|
229
|
+
when DX
|
|
230
|
+
day = [1, day / 10 * 10].max
|
|
231
|
+
when XD
|
|
232
|
+
day = day % 10 == 0 ? 10 : day % 10
|
|
233
|
+
end
|
|
234
|
+
|
|
235
|
+
[year, month, day]
|
|
236
|
+
end
|
|
237
|
+
|
|
238
|
+
def to_s(symbol = 'X')
|
|
239
|
+
masks(%w[YYYY MM DD], symbol).join('-')
|
|
240
|
+
end
|
|
241
|
+
|
|
242
|
+
# The lowest year above 0 the year digits allow:
|
|
243
|
+
# negative years have no year 0 (-00XX ends with -0001).
|
|
244
|
+
def least_year(year)
|
|
245
|
+
digits = pattern(year)[0]
|
|
246
|
+
(1..9999).find { |n| digits.match?(format('%04d', n)) }
|
|
247
|
+
end
|
|
248
|
+
|
|
249
|
+
private
|
|
250
|
+
|
|
251
|
+
# Possible months allowed by the pattern.
|
|
252
|
+
def months(year, month, day, start)
|
|
253
|
+
_, digits, day_digits = pattern(year, month, day)
|
|
254
|
+
months = (1..12).select { |m| digits.match?(format('%02d', m)) }
|
|
255
|
+
return [month] if months.empty?
|
|
256
|
+
return months if day.nil?
|
|
257
|
+
|
|
258
|
+
first = (1..31).find { |d| day_digits.match?(format('%02d', d)) }
|
|
259
|
+
fitting = months.select { |m|
|
|
260
|
+
first && ::Date.valid_date?(year, m, first, start)
|
|
261
|
+
}
|
|
262
|
+
fitting.empty? ? months : fitting
|
|
263
|
+
end
|
|
264
|
+
|
|
265
|
+
# Patterns that match the values the digits allow, e.g. /\A19..\z/.
|
|
266
|
+
def pattern(*values)
|
|
267
|
+
strings = values.compact.each_with_index.map { |v, i|
|
|
268
|
+
format(i.zero? ? '%04d' : '%02d', v)
|
|
269
|
+
}
|
|
270
|
+
masks(strings, '.').map { |digits| Regexp.new("\\A#{digits}\\z") }
|
|
271
|
+
end
|
|
272
|
+
|
|
273
|
+
def fill(year, digit)
|
|
274
|
+
masks([format('%04d', year)], digit)[0].to_i
|
|
275
|
+
end
|
|
276
|
+
end
|
|
277
|
+
end
|
data/lib/edtf/builder.rb
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
module EDTF
|
|
2
|
+
|
|
3
|
+
# Builds EDTF objects from parse results.
|
|
4
|
+
module Builder
|
|
5
|
+
|
|
6
|
+
TYPES = %i[
|
|
7
|
+
date date_time year decade century season interval set list
|
|
8
|
+
].freeze
|
|
9
|
+
|
|
10
|
+
# With centuries: true, years with only their trailing digits
|
|
11
|
+
# unspecified (19XX, 196X) are built as centuries and decades.
|
|
12
|
+
EPOCHS = {
|
|
13
|
+
Bitmask::YYXX => [Century, 100],
|
|
14
|
+
Bitmask::YYYX => [Decade, 10]
|
|
15
|
+
}.freeze
|
|
16
|
+
|
|
17
|
+
module_function
|
|
18
|
+
|
|
19
|
+
def build(result, centuries: true)
|
|
20
|
+
case result
|
|
21
|
+
when :open, :unknown, 'open', 'unknown'
|
|
22
|
+
result.to_sym
|
|
23
|
+
when Array
|
|
24
|
+
from, to = result.map { |value| build(value, centuries: centuries) }
|
|
25
|
+
from..to
|
|
26
|
+
when Hash
|
|
27
|
+
result = result.transform_keys(&:to_sym)
|
|
28
|
+
type = result[:type].to_s.to_sym
|
|
29
|
+
|
|
30
|
+
unless TYPES.include?(type)
|
|
31
|
+
raise ArgumentError,
|
|
32
|
+
"invalid parse result type: #{result[:type].inspect}"
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
unless result[:values].is_a?(Array)
|
|
36
|
+
raise ArgumentError,
|
|
37
|
+
"invalid parse result values: #{result[:values].inspect}"
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
if %i[date interval set list].include?(type)
|
|
41
|
+
send(type, result, centuries: centuries)
|
|
42
|
+
else
|
|
43
|
+
send(type, result)
|
|
44
|
+
end
|
|
45
|
+
else
|
|
46
|
+
raise ArgumentError, "invalid parse result: #{result.inspect}"
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
def date(result, centuries: true)
|
|
51
|
+
if centuries && result[:values].length == 1
|
|
52
|
+
epoch, size = EPOCHS[result[:unspecified]]
|
|
53
|
+
|
|
54
|
+
year = result[:values][0]
|
|
55
|
+
|
|
56
|
+
# Negative years stay dates: decades and centuries are not negative.
|
|
57
|
+
if epoch && !year.negative?
|
|
58
|
+
return epoch.new(year / size, **result.slice(
|
|
59
|
+
:uncertain, :approximate, :calendar, :year_zero))
|
|
60
|
+
end
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
Date.new(*astronomical(result), **result.slice(
|
|
64
|
+
:uncertain,
|
|
65
|
+
:approximate,
|
|
66
|
+
:unspecified,
|
|
67
|
+
:calendar,
|
|
68
|
+
:year_zero
|
|
69
|
+
))
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
# Results without year zero have years as written (1 BC is -1);
|
|
73
|
+
# objects store them astronomically (1 BC is 0).
|
|
74
|
+
# Year 0 has unspecified digits there: 00XX begins at year 1.
|
|
75
|
+
def astronomical(result)
|
|
76
|
+
return result[:values] unless result[:year_zero] == false
|
|
77
|
+
|
|
78
|
+
year, *values = result[:values]
|
|
79
|
+
|
|
80
|
+
year =
|
|
81
|
+
if year.zero?
|
|
82
|
+
Bitmask.new(result[:unspecified].to_i).least_year(year)
|
|
83
|
+
else
|
|
84
|
+
Period.astronomical_year(year, false)
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
[year, *values]
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
def date_time(result)
|
|
91
|
+
values = astronomical(result).take(6)
|
|
92
|
+
ms = result[:values][6]
|
|
93
|
+
values[5] += Rational(ms, 1000) if ms
|
|
94
|
+
|
|
95
|
+
precision = {
|
|
96
|
+
4 => :hour,
|
|
97
|
+
5 => :minute
|
|
98
|
+
}.fetch(values.length, :second)
|
|
99
|
+
|
|
100
|
+
DateTime.new(
|
|
101
|
+
*values,
|
|
102
|
+
offset: result[:offset],
|
|
103
|
+
precision: precision,
|
|
104
|
+
**result.slice(:year_zero)
|
|
105
|
+
)
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
def year(result)
|
|
109
|
+
Date.new(astronomical(result)[0],
|
|
110
|
+
**result.slice(:significant, :calendar, :year_zero))
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
# Decades and centuries in results were written 196 and 19.
|
|
114
|
+
def decade(result)
|
|
115
|
+
Decade.new(result[:values][0], short: true,
|
|
116
|
+
**result.slice(:uncertain, :approximate, :calendar, :year_zero))
|
|
117
|
+
end
|
|
118
|
+
|
|
119
|
+
def century(result)
|
|
120
|
+
Century.new(result[:values][0], short: true,
|
|
121
|
+
**result.slice(:uncertain, :approximate, :calendar, :year_zero))
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
def season(result)
|
|
125
|
+
year, season = astronomical(result)
|
|
126
|
+
season = hemisphere(result[:qualifier], season)
|
|
127
|
+
Season.new(year, season, **result.slice(
|
|
128
|
+
:uncertain,
|
|
129
|
+
:approximate,
|
|
130
|
+
:unspecified,
|
|
131
|
+
:calendar,
|
|
132
|
+
:year_zero))
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
def hemisphere(qualifier, season)
|
|
136
|
+
case qualifier
|
|
137
|
+
when /\Anorth/i
|
|
138
|
+
season + 4
|
|
139
|
+
when /\Asouth/i
|
|
140
|
+
season + 8
|
|
141
|
+
else
|
|
142
|
+
season
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
# An interval may end at 24:00, the end of a day (hour 24),
|
|
147
|
+
# which is kept to be written that way again.
|
|
148
|
+
def interval(result, centuries: true)
|
|
149
|
+
from, to = result[:values].map { |value|
|
|
150
|
+
build(value, centuries: centuries)
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
if to.is_a?(DateTime) && end_of_day?(result[:values][1])
|
|
154
|
+
to = to.with(t24: true)
|
|
155
|
+
end
|
|
156
|
+
Interval.new(from, to)
|
|
157
|
+
end
|
|
158
|
+
|
|
159
|
+
def end_of_day?(result)
|
|
160
|
+
result.is_a?(Hash) && (result[:values] || result['values'])[3] == 24
|
|
161
|
+
end
|
|
162
|
+
|
|
163
|
+
def set(result, centuries: true)
|
|
164
|
+
members = result[:values].map { |value|
|
|
165
|
+
build(value, centuries: centuries)
|
|
166
|
+
}
|
|
167
|
+
Set.new(*members, **result.slice(:earlier, :later))
|
|
168
|
+
end
|
|
169
|
+
|
|
170
|
+
def list(result, centuries: true)
|
|
171
|
+
members = result[:values].map { |value|
|
|
172
|
+
build(value, centuries: centuries)
|
|
173
|
+
}
|
|
174
|
+
List.new(*members, **result.slice(:earlier, :later))
|
|
175
|
+
end
|
|
176
|
+
end
|
|
177
|
+
end
|