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.
@@ -1,18 +1,292 @@
1
- class DateTime
1
+ module EDTF
2
2
 
3
- def edtf
4
- date = super
3
+ # An EDTF date-time is a regular Ruby Time:
4
+ # it acts as you would normally expect,
5
+ # but knows whether its string had an offset.
6
+ #
7
+ # Two times compare as instants, as in Ruby.
8
+ # Compared with dates and other periods,
9
+ # a time counts as its own calendar date in its own offset,
10
+ # at a precision finer than a day.
11
+ class DateTime < ::Time
12
+ include Period
5
13
 
6
- time = strftime('%H:%M:%S')
7
- time << strftime('%Z') unless skip_timezone?
14
+ ATTRIBUTES = %i[
15
+ year month day hour min sec offset precision t24
16
+ ].freeze
8
17
 
9
- [date, time].join('T')
10
- end
18
+ # The values each precision has, and its length in seconds.
19
+ PRECISION = {
20
+ hour: [4, 3600],
21
+ minute: [5, 60],
22
+ second: [6, 1]
23
+ }.freeze
11
24
 
12
- alias to_edtf edtf
25
+ # Ruby's constructors skip initialize,
26
+ # so their times would not be frozen.
27
+ private_class_method(*%i[
28
+ now at mktime local utc gm parse strptime
29
+ iso8601 xmlschema rfc2822 rfc822 httpdate
30
+ ].select { |name| ::Time.respond_to?(name) })
13
31
 
14
- def values
15
- super().concat([hour,minute,second,offset])
16
- end
32
+ # Marshal stores the values and attributes:
33
+ # Time's own format keeps no instance variables on JRuby.
34
+ undef_method :marshal_dump, :marshal_load
35
+
36
+ def _dump(_level)
37
+ Marshal.dump([
38
+ year, month, day, hour, min, sec + subsec,
39
+ offset, precision, t24?, year_zero?
40
+ ])
41
+ end
42
+
43
+ def self._load(data)
44
+ *values, offset, precision, t24, year_zero = Marshal.load(data)
45
+ new(
46
+ *values,
47
+ offset: offset,
48
+ precision: precision,
49
+ t24: t24,
50
+ year_zero: year_zero
51
+ )
52
+ end
53
+
54
+ # The offset is given in minutes; nil means a floating time.
55
+ # Minutes and seconds beyond the precision must be zero.
56
+ # A t24 time is midnight, written as 24:00 of the day before.
57
+ # With year_zero: false, years before 1 are written one lower (see Date).
58
+ def initialize(
59
+ year,
60
+ month,
61
+ day,
62
+ hour = 0,
63
+ min = 0,
64
+ sec = 0,
65
+ offset: nil,
66
+ precision: :second,
67
+ t24: false,
68
+ year_zero: true
69
+ )
70
+ precision = precision.to_sym
71
+ unless PRECISION.key?(precision)
72
+ raise ArgumentError, "invalid precision: #{precision.inspect}"
73
+ end
74
+
75
+ beyond = [min, sec].drop(PRECISION[precision][0] - 4)
76
+ unless beyond.all?(&:zero?)
77
+ raise ArgumentError,
78
+ "minutes or seconds beyond #{precision} precision"
79
+ end
80
+
81
+ super(
82
+ year,
83
+ month,
84
+ day,
85
+ hour,
86
+ min,
87
+ sec,
88
+ offset.nil? || offset.zero? ? 'UTC' : Integer(offset) * 60)
89
+
90
+ @floating = offset.nil?
91
+ @precision = precision
92
+ @t24 = !!t24
93
+ @historical = !year_zero
94
+ raise ArgumentError, 't24 needs a time at midnight' if @t24 && !midnight?
95
+ freeze
96
+ end
97
+
98
+ def floating?
99
+ !!@floating
100
+ end
101
+
102
+ def t24?
103
+ !!@t24
104
+ end
105
+
106
+ def year_zero?
107
+ !@historical
108
+ end
109
+
110
+ # In minutes, nil for floating times.
111
+ def offset
112
+ utc_offset / 60 unless floating?
113
+ end
114
+
115
+ def precision
116
+ @precision || :second
117
+ end
118
+
119
+ def values
120
+ [year, month, day, hour, min, sec].take(PRECISION[precision][0])
121
+ end
122
+
123
+ def with(**changes)
124
+ return self if changes.empty?
125
+
126
+ check_keys!(changes, ATTRIBUTES)
127
+
128
+ precision = changes.fetch(:precision, self.precision).to_sym
129
+ unless PRECISION.key?(precision)
130
+ raise ArgumentError, "invalid precision: #{precision.inspect}"
131
+ end
132
+
133
+ count = PRECISION[precision][0]
134
+ beyond = ATTRIBUTES[count...6] & changes.keys
135
+ unless beyond.empty?
136
+ raise ArgumentError,
137
+ "#{beyond.join(' and ')} beyond #{precision} precision"
138
+ end
139
+
140
+ current = [year, month, day, hour, min, sec + subsec]
141
+ values = ATTRIBUTES.take(count).zip(current).map { |name, value|
142
+ changes.fetch(name, value)
143
+ }
144
+
145
+ self.class.new(
146
+ *values,
147
+ offset: changes.fetch(:offset, offset),
148
+ precision: precision,
149
+ t24: changes.fetch(:t24) { t24? && values.drop(3).all?(&:zero?) },
150
+ year_zero: year_zero?)
151
+ end
152
+
153
+ # The calendar date in the time's own offset.
154
+ def begin
155
+ ::Date.new(year, month, day, ::Date::GREGORIAN)
156
+ end
157
+
158
+ alias_method :end, :begin
159
+
160
+ # Returns the next hour, minute, or second,
161
+ # depending on the time's precision.
162
+ def succ(by = 1)
163
+ time = self + by * PRECISION[precision][1]
164
+ values = [
165
+ time.year,
166
+ time.month,
167
+ time.day,
168
+ time.hour,
169
+ time.min,
170
+ time.sec + time.subsec
171
+ ]
172
+
173
+ self.class.new(
174
+ *values.take(PRECISION[precision][0]),
175
+ offset: offset,
176
+ precision: precision,
177
+ year_zero: year_zero?)
178
+ end
17
179
 
180
+ alias next succ
181
+
182
+ def prev(by = 1)
183
+ succ(-by)
184
+ end
185
+
186
+ # A time to the second covers only the same instant,
187
+ # one to the hour or minute the instants within it;
188
+ # dates and other periods compare by the time's calendar date.
189
+ def cover?(other)
190
+ return super unless other.is_a?(::Time)
191
+
192
+ first, other_first = to_r, other.to_r
193
+ other_span = DateTime.span(other)
194
+ return first == other_first && other_span.zero? if span.zero?
195
+
196
+ last = first + span
197
+ first <= other_first &&
198
+ (other_span.zero? ?
199
+ other_first < last : other_first + other_span <= last)
200
+ end
201
+
202
+ # Times compare by their first instant, then by their last.
203
+ def <=>(other)
204
+ return super unless other.is_a?(::Time)
205
+
206
+ order = TIME[:<=>].bind_call(self, other)
207
+ order.zero? ? span <=> DateTime.span(other) : order
208
+ end
209
+
210
+ # Returns true if other is the same instant with the same offset,
211
+ # or is floating, too.
212
+ def eql?(other)
213
+ other.is_a?(::Time) && TIME[:eql?].bind_call(self, other) &&
214
+ utc_offset == other.utc_offset &&
215
+ floating? == (other.is_a?(DateTime) && other.floating?) &&
216
+ precision == Period.precision(other)
217
+ end
218
+
219
+ def hash
220
+ extra = [
221
+ (:floating if floating?),
222
+ (precision unless precision == :second)
223
+ ].compact
224
+
225
+ if extra.empty?
226
+ TIME[:hash].bind_call(self)
227
+ else
228
+ [TIME[:hash].bind_call(self), *extra].hash
229
+ end
230
+ end
231
+
232
+ %i[getutc getgm getlocal].each do |name|
233
+ define_method(name) { |*args|
234
+ ::Time.at(self, in: utc_offset).send(name, *args)
235
+ }
236
+ end
237
+
238
+ # Time math returns plain times (on JRuby, too, which keeps the class).
239
+ %i[+ - round floor ceil].each do |name|
240
+ define_method(name) { |*args|
241
+ plain = utc? ? ::Time.at(self).utc : ::Time.at(self, in: utc_offset)
242
+ plain.public_send(name, *args)
243
+ }
244
+ end
245
+
246
+ def edtf
247
+ date, hours = self.begin, hour
248
+ date, hours = date - 1, 24 if t24?
249
+ year = Period.written_year(date.year, year_zero?)
250
+
251
+ string = format(
252
+ '%s%04d-%02d-%02dT%02d',
253
+ ('-' if year.negative?),
254
+ year.abs,
255
+ date.month,
256
+ date.day,
257
+ hours)
258
+
259
+ string += format(':%02d', min) unless precision == :hour
260
+ string += format(':%02d', sec) if precision == :second
261
+ string += ".#{strftime('%N').sub(/0+\z/, '')}" unless subsec.zero?
262
+
263
+ return string if floating?
264
+
265
+ string + (utc_offset.zero? ? 'Z' : strftime('%:z'))
266
+ end
267
+
268
+ # The length of a time in seconds: 0 for instants.
269
+ def self.span(time) # :nodoc:
270
+ return 0 unless time.is_a?(DateTime) && time.precision != :second
271
+
272
+ PRECISION[time.precision][1]
273
+ end
274
+
275
+ # Time's own methods, which Period overrides.
276
+ TIME = %i[<=> eql? hash].to_h { |name|
277
+ [name, ::Time.instance_method(name)]
278
+ }.freeze
279
+
280
+ private_constant :TIME
281
+
282
+ private
283
+
284
+ def span
285
+ DateTime.span(self)
286
+ end
287
+
288
+ def midnight?
289
+ hour.zero? && min.zero? && sec.zero? && subsec.zero?
290
+ end
291
+ end
18
292
  end
data/lib/edtf/epoch.rb CHANGED
@@ -1,109 +1,149 @@
1
1
  module EDTF
2
2
 
3
+ # Decades and centuries are dedicated periods,
4
+ # which always cover 10 or 100 years, respectively:
5
+ # the years that begin with the given digits (196 is 1960 to 1969).
6
+ # As in ISO 8601, they are never negative.
7
+ # Epoch is their shared base.
8
+ #
9
+ # Qualifiers apply to the whole epoch:
10
+ # 196~ is an approximate decade, not an approximate year.
11
+ #
12
+ # Epochs are written 196X and 19XX, or 196 and 19 if short
13
+ # (as read from those strings); both forms are the same epoch.
3
14
  class Epoch
4
- extend Forwardable
5
-
6
- include Enumerable
7
- include Comparable
15
+ include Period
8
16
 
9
17
  class << self
10
- attr_reader :duration, :format
18
+ # The number of years, the number of digits, and the precision.
19
+ attr_reader :span, :digits, :precision
20
+ end
11
21
 
12
- def current
13
- new(Date.today.year)
22
+ attr_reader :value, :calendar
23
+
24
+ def initialize(
25
+ value,
26
+ uncertain: false,
27
+ approximate: false,
28
+ short: false,
29
+ calendar: nil,
30
+ year_zero: true
31
+ )
32
+ @value = Integer(value)
33
+ unless (0...10**self.class.digits).cover?(@value)
34
+ raise ArgumentError, "invalid #{precision}: #{value}"
14
35
  end
15
36
 
16
- private :new, :current
37
+ @uncertain = qualified?(uncertain)
38
+ @approximate = qualified?(approximate)
39
+ @short = !!short
40
+ @calendar = Period.calendar(calendar)
41
+ @historical = !year_zero
42
+ freeze
17
43
  end
18
44
 
19
- attr_reader :year
20
-
21
- def_delegators :to_range, *Range.instance_methods(false).reject { |m|
22
- m.to_s =~ /^(each|min|max|cover\?|inspect|to_s)$|^\W/
23
- }
24
-
25
-
26
- def initialize(year = 0)
27
- self.year = year
45
+ def precision
46
+ self.class.precision
28
47
  end
29
48
 
30
- def year=(year)
31
- @year = (year / self.class.duration) * self.class.duration
49
+ def values
50
+ [value]
32
51
  end
33
52
 
34
- alias get year
35
- alias set year=
53
+ def uncertain?
54
+ @uncertain
55
+ end
36
56
 
37
- def cover?(other)
38
- return false unless other.respond_to?(:day_precision)
39
- other = other.day_precision
40
- min.day_precision! <= other && other <= max.day_precision!
57
+ def approximate?
58
+ @approximate
41
59
  end
42
60
 
43
- def <=>(other)
44
- case other
45
- when Date
46
- cover?(other) ? 0 : to_date <=> other
47
- when Interval
48
- (c = other <=> self) && -c
49
- when Season
50
- [min, max] <=> [other.min, other.max]
51
- when Epoch
52
- [year, self.class.duration] <=> [other.year, other.class.duration]
53
- else
54
- nil
55
- end
56
- rescue
57
- nil
61
+ def short?
62
+ @short
58
63
  end
59
64
 
60
- def ===(other)
61
- (self <=> other) == 0
62
- rescue
63
- false
65
+ # False if years are written without year 0:
66
+ # then the first century and decade (00XX, 000X) begin with year 1.
67
+ def year_zero?
68
+ !@historical
64
69
  end
65
70
 
66
- def each(&block)
67
- if block_given?
68
- to_range.each(&block)
69
- else
70
- to_enum
71
- end
71
+ def with(**changes)
72
+ return self if changes.empty?
73
+
74
+ check_keys!(changes, %i[value uncertain approximate short])
75
+
76
+ self.class.new(
77
+ changes.fetch(:value, value),
78
+ uncertain: changes.fetch(:uncertain, uncertain?),
79
+ approximate: changes.fetch(:approximate, approximate?),
80
+ short: changes.fetch(:short, short?),
81
+ calendar: calendar,
82
+ year_zero: year_zero?
83
+ )
72
84
  end
73
85
 
74
- def to_date
75
- Date.new(year).year_precision!
86
+ def begin
87
+ first = span.first.zero? && !year_zero? ? 1 : span.first
88
+ ::Date.new(first, 1, 1, Period.start(calendar))
76
89
  end
77
90
 
78
- alias min to_date
91
+ def end
92
+ ::Date.new(span.last, 12, 31, Period.start(calendar))
93
+ end
79
94
 
80
- def max
81
- to_date.advance(:years => self.class.duration - 1).end_of_year
95
+ def succ(by = 1)
96
+ with(value: value + by)
82
97
  end
83
98
 
84
- def to_range
85
- min..max
99
+ alias next succ
100
+
101
+ def prev(by = 1)
102
+ succ(-by)
86
103
  end
87
104
 
88
105
  def edtf
89
- self.class.format % (year / self.class.duration)
106
+ string = format("%0#{self.class.digits}d", value)
107
+ string += 'X' * (4 - self.class.digits) unless short?
108
+ string += '?' if uncertain?
109
+ string += '~' if approximate?
110
+ string.sub('?~', '%')
90
111
  end
91
112
 
92
- alias to_s edtf
113
+ protected
93
114
 
94
- end
115
+ def state
116
+ [value, uncertain?, approximate?, calendar, year_zero? || !value.zero?]
117
+ end
95
118
 
96
- class Century < Epoch
97
- @duration = 100.freeze
98
- @format = '%02dxx'.freeze
119
+ private
120
+
121
+ # The first and last year.
122
+ def span
123
+ low = value * self.class.span
124
+ low..(low + self.class.span - 1)
125
+ end
99
126
 
100
- public_class_method :current, :new
127
+ # Qualifiers are booleans, or bitmasks as in parse results.
128
+ def qualified?(qualifier)
129
+ case qualifier
130
+ when true, false, nil
131
+ !!qualifier
132
+ when Integer
133
+ !qualifier.zero?
134
+ else
135
+ raise ArgumentError, "invalid qualifier: #{qualifier.inspect} " \
136
+ '(an epoch is qualified as a whole)'
137
+ end
138
+ end
101
139
  end
102
140
 
103
141
  class Decade < Epoch
104
- @duration = 10.freeze
105
- @format = '%03dx'.freeze
142
+ @span, @digits, @precision = 10, 3, :decade
143
+ end
106
144
 
107
- public_class_method :current, :new
145
+ class Century < Epoch
146
+ @span, @digits, @precision = 100, 2, :century
108
147
  end
148
+
109
149
  end
@@ -0,0 +1,118 @@
1
+ require 'strscan'
2
+ require 'racc/parser'
3
+
4
+ module EDTF
5
+ # The base class of the generated grammars (see EDTF::Parser).
6
+ # A grammar returns plain parse results.
7
+ class Grammar < Racc::Parser # :nodoc:
8
+
9
+ PARTS = {
10
+ year: Bitmask::YEAR,
11
+ month: Bitmask::MONTH,
12
+ day: Bitmask::DAY
13
+ }.freeze
14
+
15
+ EXTENSIONS = %i[season_uncertainty season_intervals basic_offset].freeze
16
+
17
+ # Season intervals are off by default, as in edtf.js;
18
+ # qualified seasons are on (EDTF-Ruby 4.x read them as a whole).
19
+ DEFAULT_EXTENSIONS = %i[season_uncertainty basic_offset].freeze
20
+
21
+ class ParseError < ArgumentError; end
22
+
23
+ attr_reader :deprecations
24
+
25
+ # Exponents let short strings stand for huge years (Y3E9999999 has ten
26
+ # million digits); years beyond max_year_digits are rejected unread.
27
+ def initialize(extensions: DEFAULT_EXTENSIONS, max_year_digits: 100)
28
+ @extensions = extensions
29
+ @max_year_digits = max_year_digits
30
+ end
31
+
32
+ def parse(input, debug: false)
33
+ unless input.encoding == Encoding::UTF_8 || input.ascii_only?
34
+ raise ParseError, "invalid encoding #{input.encoding}"
35
+ end
36
+
37
+ @yydebug = debug
38
+ @src = StringScanner.new(input)
39
+ @deprecations = []
40
+ do_parse
41
+ end
42
+
43
+ def on_error(tid, value, stack)
44
+ raise ParseError,
45
+ "failed to parse date: unexpected '#{value}' at #{stack.inspect}"
46
+ end
47
+
48
+ def deprecate(name)
49
+ @deprecations << name
50
+ end
51
+
52
+ def extension(name)
53
+ return if @extensions.include?(name)
54
+ raise ArgumentError, "extension #{name} is turned off"
55
+ end
56
+
57
+ # Rejects days the month cannot have in any year;
58
+ # the parser checks leap days in the date's calendar.
59
+ def check_day(year, month, day)
60
+ if day > Bitmask::MAXDAYS[month - 1]
61
+ raise ArgumentError,
62
+ "invalid date (invalid days #{day} for month #{month})"
63
+ end
64
+
65
+ [year, month, day]
66
+ end
67
+
68
+ # [1, 9, 8, 4] -> 1984
69
+ def number(digits)
70
+ digits.reduce(0) { |n, digit| 10 * n + digit }
71
+ end
72
+
73
+ def date(*values, **attributes)
74
+ { type: :date, values: values, **attributes }
75
+ end
76
+
77
+ def extend_date(result, *values)
78
+ result.merge(values: result[:values] + values)
79
+ end
80
+
81
+ def exponent(sgnd, exponent)
82
+ if sgnd.abs.to_s.length + exponent > @max_year_digits
83
+ raise ArgumentError,
84
+ "year too large: more than #{@max_year_digits} digits"
85
+ end
86
+
87
+ sgnd * 10**exponent
88
+ end
89
+
90
+ def year(value, level, significant = nil)
91
+ result = { type: :year, level: level, values: [value] }
92
+ result[:significant] = significant if significant
93
+ result
94
+ end
95
+
96
+ def interval(from, to)
97
+ { type: :interval, values: [from, to] }
98
+ end
99
+
100
+ # Qualifies the given parts (a Symbol, an Array, or a mask) of a result,
101
+ # or the whole date if no parts are given.
102
+ def qualify(result, qualifiers, parts = nil)
103
+ mask = case parts
104
+ when nil
105
+ Date::MASKS[result[:values].length]
106
+ when Integer
107
+ parts
108
+ else
109
+ Array(parts).sum { |part| PARTS[part] }
110
+ end
111
+
112
+ qualifiers.each do |q|
113
+ result[q] = (result[q] || 0) | mask
114
+ end
115
+ result
116
+ end
117
+ end
118
+ end