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/README.md
CHANGED
|
@@ -1,138 +1,154 @@
|
|
|
1
1
|
EDTF-Ruby
|
|
2
2
|
=========
|
|
3
|
-
[](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
|
|
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
|
|
12
|
-
|
|
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
|
-
|
|
45
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
68
|
-
|
|
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
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
which
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
84
|
-
|
|
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
|
-
|
|
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
|
|
90
|
-
|
|
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
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
|
|
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
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
|
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
|
-
|
|
166
|
-
the
|
|
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
|
-
|
|
169
|
-
|
|
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
|
-
|
|
213
|
+
EDTF('1999-03-XX').end.to_s #-> "1999-03-31"
|
|
214
|
+
EDTF('201X-05').succ.edtf #-> "201X-06"
|
|
184
215
|
|
|
185
|
-
|
|
186
|
-
|
|
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
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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
|
-
|
|
201
|
-
> draft_d.edtf
|
|
202
|
-
=> "1999-03-XX"
|
|
223
|
+
### Enumerating dates
|
|
203
224
|
|
|
204
|
-
|
|
205
|
-
do not factor into date calculations
|
|
206
|
-
(like comparisons or successors etc.).
|
|
225
|
+
Dates step by their precision:
|
|
207
226
|
|
|
208
|
-
EDTF
|
|
227
|
+
EDTF('2016-02-28').succ.edtf #-> "2016-02-29"
|
|
228
|
+
EDTF('2017-02-28').succ.edtf #-> "2017-03-01"
|
|
209
229
|
|
|
210
|
-
|
|
211
|
-
|
|
230
|
+
`upto` and `downto` yield all the dates, by precision,
|
|
231
|
+
from one date to another:
|
|
212
232
|
|
|
213
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
223
|
-
intervals
|
|
224
|
-
but
|
|
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
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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
|
-
|
|
236
|
-
=> true
|
|
305
|
+
i.cover?(Date.new(1987, 4, 13)) #-> true
|
|
237
306
|
|
|
238
307
|
The day is still covered by the interval.
|
|
239
|
-
|
|
240
|
-
Additionally, precision plays into the way intervals are enumerated:
|
|
308
|
+
Precision also plays into the way intervals are enumerated:
|
|
241
309
|
|
|
242
|
-
|
|
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
|
-
|
|
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
|
|
317
|
+
and map each step to its first year.
|
|
318
|
+
This also works with varying precisions:
|
|
252
319
|
|
|
253
|
-
|
|
254
|
-
|
|
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
|
-
|
|
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
|
-
|
|
264
|
-
|
|
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
|
-
|
|
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
|
|
274
|
-
and the `choice` attribute.
|
|
360
|
+
In EDTF-Ruby, these are covered by `EDTF::Set` and `EDTF::List`.
|
|
275
361
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
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
|
-
|
|
288
|
-
|
|
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
|
-
|
|
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
|
-
|
|
302
|
-
|
|
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
|
-
|
|
384
|
+
s.earlier? #-> false
|
|
385
|
+
s.with(earlier: true).edtf #-> "{..1667,1668,1670..1672}"
|
|
305
386
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
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
|
-
|
|
316
|
-
|
|
317
|
-
|
|
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
|
-
|
|
321
|
-
|
|
322
|
-
|
|
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
|
-
|
|
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
|
-
|
|
335
|
-
|
|
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
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
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]
|
|
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
|
-
|
|
393
|
-
|
|
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]
|
|
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
|
-------
|