field_struct 0.15.0 → 1.0.0.pre1
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/.claude-plugin/marketplace.json +13 -0
- data/.claude-plugin/plugin.json +9 -0
- data/AGENTS.md +47 -54
- data/CHANGELOG.md +53 -640
- data/LICENSE.txt +21 -0
- data/README.md +33 -628
- data/USAGE.md +771 -715
- data/docs/getting_started.md +139 -325
- data/lib/field_struct/base.rb +241 -1149
- data/lib/field_struct/class_macros.rb +163 -0
- data/lib/field_struct/describer.rb +167 -0
- data/lib/field_struct/errors.rb +182 -62
- data/lib/field_struct/exceptions.rb +40 -0
- data/lib/field_struct/field.rb +69 -135
- data/lib/field_struct/field_builder.rb +110 -0
- data/lib/field_struct/field_checks.rb +50 -0
- data/lib/field_struct/introspection.rb +199 -0
- data/lib/field_struct/json_codec.rb +240 -0
- data/lib/field_struct/metadata.rb +65 -260
- data/lib/field_struct/model_name.rb +27 -27
- data/lib/field_struct/option_checker.rb +121 -0
- data/lib/field_struct/partial.rb +49 -0
- data/lib/field_struct/presence.rb +45 -0
- data/lib/field_struct/rbs.rb +151 -271
- data/lib/field_struct/registered_option.rb +113 -0
- data/lib/field_struct/registry.rb +40 -50
- data/lib/field_struct/restrictions.rb +90 -0
- data/lib/field_struct/scaffold.rb +274 -301
- data/lib/field_struct/suggestion.rb +33 -0
- data/lib/field_struct/types/array.rb +147 -126
- data/lib/field_struct/types/base.rb +113 -124
- data/lib/field_struct/types/big_decimal.rb +59 -55
- data/lib/field_struct/types/binary.rb +18 -25
- data/lib/field_struct/types/boolean.rb +74 -97
- data/lib/field_struct/types/builtin.rb +32 -0
- data/lib/field_struct/types/date.rb +23 -137
- data/lib/field_struct/types/datetime.rb +30 -139
- data/lib/field_struct/types/element_options.rb +51 -0
- data/lib/field_struct/types/email.rb +27 -38
- data/lib/field_struct/types/float.rb +58 -56
- data/lib/field_struct/types/format_presets.rb +30 -0
- data/lib/field_struct/types/hash.rb +144 -0
- data/lib/field_struct/types/immutable_string.rb +16 -9
- data/lib/field_struct/types/integer.rb +74 -102
- data/lib/field_struct/types/nested.rb +57 -58
- data/lib/field_struct/types/preset_resolver.rb +9 -24
- data/lib/field_struct/types/rfc3339_format.rb +70 -153
- data/lib/field_struct/types/string.rb +48 -46
- data/lib/field_struct/types/symbol.rb +23 -20
- data/lib/field_struct/types/temporal.rb +232 -0
- data/lib/field_struct/types/time.rb +32 -145
- data/lib/field_struct/types/union.rb +111 -65
- data/lib/field_struct/types/union_pick.rb +139 -0
- data/lib/field_struct/types/url.rb +24 -35
- data/lib/field_struct/types/uuid.rb +24 -35
- data/lib/field_struct/types/value.rb +14 -9
- data/lib/field_struct/types/zone.rb +118 -0
- data/lib/field_struct/version.rb +3 -3
- data/lib/field_struct.rb +102 -122
- data/sig/field_struct.rbs +1180 -2300
- data/sig/manifest.yaml +6 -0
- data/skills/field-struct/SKILL.md +73 -159
- metadata +37 -28
- data/CODE_OF_CONDUCT.md +0 -132
- data/UPGRADING.md +0 -743
- data/lib/field_struct/error.rb +0 -48
- data/lib/field_struct/types/temporal_parser.rb +0 -93
- data/lib/field_struct/types/time_format_resolver.rb +0 -54
- data/lib/field_struct/types/zone_option.rb +0 -267
data/lib/field_struct/error.rb
DELETED
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
module FieldStruct
|
|
4
|
-
# Base class for every error FieldStruct raises. Catch this to handle
|
|
5
|
-
# any library error generically.
|
|
6
|
-
class Error < StandardError; end
|
|
7
|
-
|
|
8
|
-
# Raised by the setter pipeline when a value cannot be coerced into a
|
|
9
|
-
# field's declared type and the class's +coercion_policy+ is +:raise+.
|
|
10
|
-
#
|
|
11
|
-
# Carries the field name and the original underlying error for callers
|
|
12
|
-
# that want to inspect what happened.
|
|
13
|
-
class CoercionError < Error
|
|
14
|
-
# @return [Symbol, nil] the field whose setter triggered the failure
|
|
15
|
-
attr_reader :field_name
|
|
16
|
-
|
|
17
|
-
# @return [StandardError, nil] the underlying error from the type's coerce
|
|
18
|
-
attr_reader :original
|
|
19
|
-
|
|
20
|
-
# @param message [String]
|
|
21
|
-
# @param field_name [Symbol, nil]
|
|
22
|
-
# @param original [StandardError, nil]
|
|
23
|
-
def initialize(message, field_name: nil, original: nil)
|
|
24
|
-
super(message)
|
|
25
|
-
@field_name = field_name
|
|
26
|
-
@original = original
|
|
27
|
-
end
|
|
28
|
-
end
|
|
29
|
-
|
|
30
|
-
# Raised when a field setter on a class marked +immutable!+ is called
|
|
31
|
-
# after construction.
|
|
32
|
-
class ImmutableError < Error; end
|
|
33
|
-
|
|
34
|
-
# Raised by {Base#initialize} / {Base#assign_attributes} when the input
|
|
35
|
-
# hash includes a key that is not a declared field on the class and
|
|
36
|
-
# the +unknown_attributes+ policy is +:raise+.
|
|
37
|
-
class UnknownAttributeError < Error
|
|
38
|
-
# @return [Array<Symbol>] the offending keys
|
|
39
|
-
attr_reader :keys
|
|
40
|
-
|
|
41
|
-
# @param message [String]
|
|
42
|
-
# @param keys [Array<Symbol>]
|
|
43
|
-
def initialize(message, keys: [])
|
|
44
|
-
super(message)
|
|
45
|
-
@keys = keys
|
|
46
|
-
end
|
|
47
|
-
end
|
|
48
|
-
end
|
|
@@ -1,93 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
require 'date'
|
|
4
|
-
|
|
5
|
-
module FieldStruct
|
|
6
|
-
module Types
|
|
7
|
-
# Shared String-parsing rules for {Date}, {Time} and {DateTime}.
|
|
8
|
-
#
|
|
9
|
-
# Three rules the stdlib parsers leave to their caller. Each of them is a
|
|
10
|
-
# case where the stdlib answers a question it was not asked, confidently.
|
|
11
|
-
#
|
|
12
|
-
# **Anchoring.** +strptime+ matches a PREFIX and discards the rest.
|
|
13
|
-
# +Date.strptime('2026-07-031', '%Y-%m-%d')+ returns the 3rd and throws the
|
|
14
|
-
# trailing +1+ away; +'2026-07-03T10:30:00+0000-NONSENSE'+ parses clean
|
|
15
|
-
# under the +iso8601+ preset. A declared +format:+ is a contract about the
|
|
16
|
-
# whole string, so anything left over is refused. (Leading whitespace needs
|
|
17
|
-
# no rule — +Date._strptime+ already returns +nil+ for it.)
|
|
18
|
-
#
|
|
19
|
-
# **Civil validity.** +Date.strptime+ and +DateTime.strptime+ refuse the
|
|
20
|
-
# 30th of February. +Time+ does not: +Time.parse+, +Time.strptime+ and
|
|
21
|
-
# +Time.new+ all roll it forward to 2 March and say nothing. All three
|
|
22
|
-
# types refuse it here.
|
|
23
|
-
#
|
|
24
|
-
# **Completeness.** With no declared format the stdlib parsers fill in
|
|
25
|
-
# whatever the string omits, from *today*: +Time.parse('10:30')+ is today
|
|
26
|
-
# at 10:30, +'July'+ is the 1st of July this year, +'12'+ is the 12th of
|
|
27
|
-
# this month. A value whose meaning depends on when it was parsed is not a
|
|
28
|
-
# value, so a string with no declared format must name a whole day.
|
|
29
|
-
#
|
|
30
|
-
# Anchoring is trailing-junk rejection and nothing more. Widths, sign and
|
|
31
|
-
# case stay strptime-lenient for a hand-written format: +%m+ and +%d+
|
|
32
|
-
# accept one or two digits, which is strptime's contract rather than a
|
|
33
|
-
# defect. Strictness for the built-in presets is a separate concern.
|
|
34
|
-
module TemporalParser
|
|
35
|
-
# Validate a String against a declared format.
|
|
36
|
-
#
|
|
37
|
-
# @param value [::String] the raw string
|
|
38
|
-
# @param format [::String] a resolved strftime/strptime format
|
|
39
|
-
# @return [::Hash{::Symbol => Object}] the parsed fragments
|
|
40
|
-
# @raise [ArgumentError] when the string does not match the format, has
|
|
41
|
-
# characters left over, or names a day that does not exist
|
|
42
|
-
def self.strptime_parts(value, format)
|
|
43
|
-
parts = ::Date._strptime(value, format)
|
|
44
|
-
raise ArgumentError, "does not match format #{format.inspect}" if parts.nil?
|
|
45
|
-
|
|
46
|
-
if parts.key?(:leftover)
|
|
47
|
-
raise ArgumentError,
|
|
48
|
-
"does not match format #{format.inspect} — unexpected trailing characters"
|
|
49
|
-
end
|
|
50
|
-
|
|
51
|
-
ensure_real_day!(parts)
|
|
52
|
-
parts
|
|
53
|
-
end
|
|
54
|
-
|
|
55
|
-
# Validate a String with no declared format.
|
|
56
|
-
#
|
|
57
|
-
# @param value [::String] the raw string
|
|
58
|
-
# @return [::Hash{::Symbol => Object}] the parsed fragments
|
|
59
|
-
# @raise [ArgumentError] when the string names only part of a day, or a
|
|
60
|
-
# day that does not exist
|
|
61
|
-
def self.parse_parts(value)
|
|
62
|
-
parts = ::Date._parse(value)
|
|
63
|
-
ensure_whole_day!(parts)
|
|
64
|
-
ensure_real_day!(parts)
|
|
65
|
-
parts
|
|
66
|
-
end
|
|
67
|
-
|
|
68
|
-
# @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
|
|
69
|
-
# @return [void]
|
|
70
|
-
# @raise [ArgumentError] when year, month or day is missing
|
|
71
|
-
def self.ensure_whole_day!(parts)
|
|
72
|
-
return if parts[:year] && parts[:mon] && parts[:mday]
|
|
73
|
-
|
|
74
|
-
# The value is deliberately not echoed: FieldStruct wraps this as
|
|
75
|
-
# "could not be coerced: <message>" and that string reaches API
|
|
76
|
-
# responses and audit rows.
|
|
77
|
-
raise ArgumentError, 'expected a date with a year, a month and a day'
|
|
78
|
-
end
|
|
79
|
-
|
|
80
|
-
# @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
|
|
81
|
-
# or +Date._strptime+
|
|
82
|
-
# @return [void]
|
|
83
|
-
# @raise [ArgumentError] when the fragments name a day that never existed
|
|
84
|
-
def self.ensure_real_day!(parts)
|
|
85
|
-
year, month, day = parts.values_at(:year, :mon, :mday)
|
|
86
|
-
return if year.nil? || month.nil? || day.nil?
|
|
87
|
-
return if ::Date.valid_civil?(year, month, day)
|
|
88
|
-
|
|
89
|
-
raise ArgumentError, 'invalid date'
|
|
90
|
-
end
|
|
91
|
-
end
|
|
92
|
-
end
|
|
93
|
-
end
|
|
@@ -1,54 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
module FieldStruct
|
|
4
|
-
module Types
|
|
5
|
-
# Shared +format:+ option resolution for {Date}/{Time}/{DateTime}.
|
|
6
|
-
# Each of those types calls +TimeFormatResolver.call(options, presets)+
|
|
7
|
-
# from its +resolve_options+ class method.
|
|
8
|
-
#
|
|
9
|
-
# A declared +format:+ is VALIDATED at declaration time and kept exactly as
|
|
10
|
-
# the user wrote it; it is resolved to a strftime string later, at coerce
|
|
11
|
-
# and render time, by {.resolve}.
|
|
12
|
-
#
|
|
13
|
-
# Keeping the declaration is the point. The Symbol used to be overwritten
|
|
14
|
-
# with the strftime String it expands to, which destroyed the only fact a
|
|
15
|
-
# documentation generator actually wants — that the field is +:iso8601+,
|
|
16
|
-
# not some anonymous String of percent-escapes. Recovering the name by
|
|
17
|
-
# reverse-mapping the String worked only while no two presets shared a
|
|
18
|
-
# value, which is luck rather than a contract.
|
|
19
|
-
module TimeFormatResolver
|
|
20
|
-
# Validate a declared +format:+ and return the options unchanged.
|
|
21
|
-
#
|
|
22
|
-
# @param options [::Hash{::Symbol => Object, nil}] the per-field options as written
|
|
23
|
-
# @param presets [::Hash{::Symbol => ::String}] the type's preset table
|
|
24
|
-
# @return [::Hash{::Symbol => Object, nil}] +options+, unmodified
|
|
25
|
-
# @raise [ArgumentError] when +format:+ is the wrong shape, or names a
|
|
26
|
-
# preset the type does not have — at declaration time, not at first use
|
|
27
|
-
def self.call(options, presets)
|
|
28
|
-
return options unless options.key?(:format)
|
|
29
|
-
|
|
30
|
-
fmt = options[:format]
|
|
31
|
-
return options if fmt.is_a?(::String) || fmt.is_a?(::Regexp) || fmt.nil?
|
|
32
|
-
raise ArgumentError, "format: must be a String, Regexp, or Symbol — got #{fmt.class}" unless fmt.is_a?(::Symbol)
|
|
33
|
-
|
|
34
|
-
resolve(fmt, presets) # raises on an unknown name; the result is discarded
|
|
35
|
-
options
|
|
36
|
-
end
|
|
37
|
-
|
|
38
|
-
# Resolve a declared +format:+ to a strftime/strptime String.
|
|
39
|
-
#
|
|
40
|
-
# @param format [::String, ::Symbol, nil] as declared
|
|
41
|
-
# @param presets [::Hash{::Symbol => ::String}] the type's preset table
|
|
42
|
-
# @return [::String, nil] +nil+ when no format is declared
|
|
43
|
-
# @raise [ArgumentError] when the Symbol names no preset in the table
|
|
44
|
-
def self.resolve(format, presets)
|
|
45
|
-
return format if format.nil? || format.is_a?(::String)
|
|
46
|
-
|
|
47
|
-
presets.fetch(format) do
|
|
48
|
-
raise ArgumentError,
|
|
49
|
-
"unknown time format preset #{format.inspect}. Available: #{presets.keys.inspect}"
|
|
50
|
-
end
|
|
51
|
-
end
|
|
52
|
-
end
|
|
53
|
-
end
|
|
54
|
-
end
|
|
@@ -1,267 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
require 'date'
|
|
4
|
-
require 'time'
|
|
5
|
-
|
|
6
|
-
module FieldStruct
|
|
7
|
-
module Types
|
|
8
|
-
# The +zone:+ option shared by {Time} and {DateTime}.
|
|
9
|
-
#
|
|
10
|
-
# A zone-less string (+"2026-10-22 10:00"+) names a wall-clock time, not an
|
|
11
|
-
# instant: by default +:time+ reads it in the *process* zone and +:datetime+
|
|
12
|
-
# in UTC, so the same input meant different instants on different servers.
|
|
13
|
-
# +zone:+ supplies the missing offset, so it means one instant everywhere.
|
|
14
|
-
#
|
|
15
|
-
# It only fills in an offset that is MISSING. A string with an offset, a
|
|
16
|
-
# +Time+, a +DateTime+ (and ActiveSupport's TimeWithZone) keep theirs; a
|
|
17
|
-
# +Date+, which has none, becomes midnight in the zone.
|
|
18
|
-
#
|
|
19
|
-
# Accepted values are +"UTC"+, fixed offsets +"±HH:MM"+ and IANA
|
|
20
|
-
# Area/Location names (+"America/Denver"+). A fixed offset is the same all
|
|
21
|
-
# year. A name is read through tzinfo's zone database, so a wall-clock time
|
|
22
|
-
# gets the offset in force at that date and an instant (an epoch) the
|
|
23
|
-
# offset in force at that instant. tzinfo is required only when a field
|
|
24
|
-
# declares a name.
|
|
25
|
-
#
|
|
26
|
-
# Daylight-saving edges, for a name:
|
|
27
|
-
#
|
|
28
|
-
# - A wall-clock time the zone skips (02:30 on a spring-forward day) is
|
|
29
|
-
# refused, as a 30 February is: it names no instant. ActiveSupport moves
|
|
30
|
-
# it an hour forward instead; FieldStruct does not guess.
|
|
31
|
-
# - A wall-clock time the zone repeats (01:30 on a fall-back day) is read
|
|
32
|
-
# at its daylight-time offset — the earlier instant — which is what
|
|
33
|
-
# ActiveSupport's TimeWithZone picks, so a Rails app sees the same answer.
|
|
34
|
-
# - A +Date+ whose midnight the zone skips becomes the first moment of that
|
|
35
|
-
# day (01:00 in Santiago on its spring-forward day), as
|
|
36
|
-
# +Date#in_time_zone+ does.
|
|
37
|
-
#
|
|
38
|
-
# The value returned is a plain +::Time+ (or +::DateTime+) carrying the
|
|
39
|
-
# offset, never a +TZInfo::TimeWithOffset+; it does not carry the zone
|
|
40
|
-
# itself, so arithmetic on it keeps that offset rather than following DST.
|
|
41
|
-
#
|
|
42
|
-
# Refused: abbreviations and legacy aliases with no +/+ (+"MST"+ is a fixed
|
|
43
|
-
# -07:00 in the database, not Mountain time with DST) and Rails' friendly
|
|
44
|
-
# names (+"Mountain Time (US & Canada)"+), which only exist when
|
|
45
|
-
# ActiveSupport is loaded and so would make a declaration valid in one
|
|
46
|
-
# process and invalid in another (invariant 7).
|
|
47
|
-
module ZoneOption
|
|
48
|
-
# A fixed UTC offset, colon required.
|
|
49
|
-
# @return [::Regexp]
|
|
50
|
-
OFFSET = /\A([+-])(\d{2}):(\d{2})\z/
|
|
51
|
-
|
|
52
|
-
# Refuse a +zone:+ value FieldStruct cannot read, at declaration. A
|
|
53
|
-
# non-String is left for the option-shape check to report.
|
|
54
|
-
#
|
|
55
|
-
# @param type_name [::String] the type's short name, for the message
|
|
56
|
-
# @param options [::Hash{::Symbol => Object, nil}] the per-field options
|
|
57
|
-
# @return [::Hash{::Symbol => Object, nil}] the options, unchanged
|
|
58
|
-
# @raise [ArgumentError] when +zone:+ is a String that is not +"UTC"+, a
|
|
59
|
-
# valid +±HH:MM+ offset or an IANA name in the zone database, or when
|
|
60
|
-
# no zone database can be found
|
|
61
|
-
def self.validate!(type_name, options)
|
|
62
|
-
zone = options[:zone]
|
|
63
|
-
return options unless zone.is_a?(::String)
|
|
64
|
-
return options if offset_seconds(zone)
|
|
65
|
-
|
|
66
|
-
raise ArgumentError, refusal(type_name, zone) unless zone.include?('/')
|
|
67
|
-
|
|
68
|
-
load_timezone(type_name, zone)
|
|
69
|
-
options
|
|
70
|
-
end
|
|
71
|
-
|
|
72
|
-
# @param type_name [::String] the type's short name
|
|
73
|
-
# @param zone [::String] the refused +zone:+
|
|
74
|
-
# @return [::String] the declaration error, with a hint for the
|
|
75
|
-
# shape of +zone+
|
|
76
|
-
def self.refusal(type_name, zone)
|
|
77
|
-
hint = if zone.match?(/[ ()&]/)
|
|
78
|
-
'Rails zone names are an ActiveSupport alias, not IANA names, and exist only when ' \
|
|
79
|
-
'ActiveSupport is loaded: use the name it maps to (ActiveSupport::TimeZone::MAPPING[name]).'
|
|
80
|
-
elsif zone.include?('/')
|
|
81
|
-
'The zone database has no zone by that name.'
|
|
82
|
-
else
|
|
83
|
-
'Use an Area/Location name: abbreviations and aliases are refused ("MST" is a fixed ' \
|
|
84
|
-
'-07:00 in the zone database, not Mountain time with DST), and an offset needs its colon.'
|
|
85
|
-
end
|
|
86
|
-
"zone: on #{type_name} expects an IANA name like \"America/Denver\", \"UTC\" or a UTC offset " \
|
|
87
|
-
"like \"-06:00\", got #{zone.inspect}. #{hint}"
|
|
88
|
-
end
|
|
89
|
-
|
|
90
|
-
# Look up (and cache) a zone by name, requiring tzinfo on first use.
|
|
91
|
-
#
|
|
92
|
-
# @param type_name [::String] the type's short name, for the message
|
|
93
|
-
# @param zone [::String] an IANA name
|
|
94
|
-
# @return [Object] the +TZInfo::Timezone+
|
|
95
|
-
# @raise [ArgumentError] when the name is unknown, or no zone data is
|
|
96
|
-
# installed
|
|
97
|
-
def self.load_timezone(type_name, zone)
|
|
98
|
-
require 'tzinfo'
|
|
99
|
-
@timezones ||= {}
|
|
100
|
-
@timezones[zone] ||= ::TZInfo::Timezone.get(zone)
|
|
101
|
-
rescue ::TZInfo::InvalidTimezoneIdentifier
|
|
102
|
-
raise ArgumentError, refusal(type_name, zone)
|
|
103
|
-
rescue ::TZInfo::DataSourceNotFound
|
|
104
|
-
raise ArgumentError,
|
|
105
|
-
"zone: on #{type_name} names #{zone.inspect}, but no time zone data was found on this system. " \
|
|
106
|
-
'Add the tzinfo-data gem to your Gemfile (or install the OS zoneinfo package).'
|
|
107
|
-
end
|
|
108
|
-
|
|
109
|
-
# @param zone [::String] an IANA name {.validate!} accepted
|
|
110
|
-
# @return [Object] the cached +TZInfo::Timezone+
|
|
111
|
-
# @raise [ArgumentError] for a name {.validate!} would refuse, when a
|
|
112
|
-
# type is called directly with one
|
|
113
|
-
def self.timezone(zone)
|
|
114
|
-
cached = @timezones && @timezones[zone]
|
|
115
|
-
return cached if cached
|
|
116
|
-
raise ArgumentError, refusal('the field', zone) unless zone.include?('/')
|
|
117
|
-
|
|
118
|
-
load_timezone('the field', zone)
|
|
119
|
-
end
|
|
120
|
-
|
|
121
|
-
# @param zone [::String] a declared +zone:+
|
|
122
|
-
# @return [::Integer, nil] seconds east of UTC, or +nil+ when +zone+ is
|
|
123
|
-
# not a value {.validate!} accepts
|
|
124
|
-
def self.offset_seconds(zone)
|
|
125
|
-
return 0 if zone == 'UTC'
|
|
126
|
-
|
|
127
|
-
match = OFFSET.match(zone)
|
|
128
|
-
return nil if match.nil?
|
|
129
|
-
|
|
130
|
-
hours = Integer(match[2], 10)
|
|
131
|
-
minutes = Integer(match[3], 10)
|
|
132
|
-
return nil if hours > 23 || minutes > 59
|
|
133
|
-
|
|
134
|
-
(match[1] == '-' ? -1 : 1) * ((hours * 3600) + (minutes * 60))
|
|
135
|
-
end
|
|
136
|
-
|
|
137
|
-
# Whether parsed fragments leave the offset to +zone:+.
|
|
138
|
-
#
|
|
139
|
-
# @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
|
|
140
|
-
# or +Date._strptime+
|
|
141
|
-
# @return [Boolean] +true+ when the string named no offset at all
|
|
142
|
-
# @raise [ArgumentError] when the string names a zone the stdlib cannot
|
|
143
|
-
# turn into an offset (+"XYZ"+, +"America/Denver"+): +zone:+ never
|
|
144
|
-
# overrides a zone the input stated
|
|
145
|
-
def self.zoneless?(parts)
|
|
146
|
-
# An epoch (%s / %Q) is an instant already; {.time_at} keeps it and
|
|
147
|
-
# only places it at the zone's offset, as it does for any other input.
|
|
148
|
-
return false unless parts[:offset].nil?
|
|
149
|
-
return true if parts[:zone].nil?
|
|
150
|
-
|
|
151
|
-
# The input is not echoed — see Types::Time#coerce.
|
|
152
|
-
raise ArgumentError, 'names a time zone with no fixed offset, which zone: does not override'
|
|
153
|
-
end
|
|
154
|
-
|
|
155
|
-
# Read a zone-less String as a wall-clock time in +zone+.
|
|
156
|
-
#
|
|
157
|
-
# @param value [::String] a string {.zoneless?} accepted
|
|
158
|
-
# @param format [::String, nil] a resolved strptime format, or +nil+ for
|
|
159
|
-
# the no-format path (which has already required a whole day)
|
|
160
|
-
# @param zone [::String] a declared +zone:+
|
|
161
|
-
# @param parts [::Hash{::Symbol => Object}] the fragments the string
|
|
162
|
-
# parsed to; an epoch (+%s+ / +%Q+) shows up as +:seconds+
|
|
163
|
-
# @return [::Time] at +zone+'s offset (+utc?+ for +"UTC"+)
|
|
164
|
-
# @raise [ArgumentError] when +zone+ is a name and the wall-clock time
|
|
165
|
-
# falls in a gap the zone skips
|
|
166
|
-
def self.time_at(value, format, zone, parts)
|
|
167
|
-
offset = offset_seconds(zone)
|
|
168
|
-
return named_time_at(value, format, timezone(zone), parts) if offset.nil?
|
|
169
|
-
|
|
170
|
-
time = if format
|
|
171
|
-
# Appending the offset lets strptime do everything else as usual.
|
|
172
|
-
# Given an offset, it also fills a date the format omits from today
|
|
173
|
-
# *at that offset*, where plain strptime uses the process zone's
|
|
174
|
-
# today, and places an epoch (%s) at that offset.
|
|
175
|
-
::Time.strptime("#{value} #{offset_text(offset)}", "#{format} %z")
|
|
176
|
-
else
|
|
177
|
-
# DateTime.parse reads the wall clock with no zone involved, so a
|
|
178
|
-
# time the process zone skips for DST (02:30 on a spring-forward day)
|
|
179
|
-
# is kept rather than moved, as Time.parse would.
|
|
180
|
-
wall = ::DateTime.parse(value)
|
|
181
|
-
::Time.new(wall.year, wall.mon, wall.mday, wall.hour, wall.min, wall.sec + wall.sec_fraction, offset)
|
|
182
|
-
end
|
|
183
|
-
zone == 'UTC' ? time.utc : time
|
|
184
|
-
end
|
|
185
|
-
|
|
186
|
-
# {.time_at} for an IANA name: the offset depends on the date.
|
|
187
|
-
#
|
|
188
|
-
# @param value [::String] the zone-less string
|
|
189
|
-
# @param format [::String, nil] a resolved strptime format, or +nil+
|
|
190
|
-
# @param timezone [Object] a +TZInfo::Timezone+
|
|
191
|
-
# @param parts [::Hash{::Symbol => Object}] the parsed fragments
|
|
192
|
-
# @return [::Time]
|
|
193
|
-
def self.named_time_at(value, format, timezone, parts)
|
|
194
|
-
# An epoch is an instant already: keep it, at the offset of that instant.
|
|
195
|
-
return in_zone(::Time.strptime(value, format), timezone) if format && parts.key?(:seconds)
|
|
196
|
-
|
|
197
|
-
wall = if format
|
|
198
|
-
# The offset in force NOW only decides which day "today" is when
|
|
199
|
-
# the format omits the date; the wall clock is resolved below.
|
|
200
|
-
now = offset_text(timezone.period_for(::Time.now).observed_utc_offset)
|
|
201
|
-
::Time.strptime("#{value} #{now}", "#{format} %z")
|
|
202
|
-
else
|
|
203
|
-
::DateTime.parse(value)
|
|
204
|
-
end
|
|
205
|
-
sec = wall.sec + (wall.is_a?(::DateTime) ? wall.sec_fraction : wall.subsec)
|
|
206
|
-
local(timezone, [wall.year, wall.mon, wall.mday, wall.hour, wall.min, sec])
|
|
207
|
-
end
|
|
208
|
-
|
|
209
|
-
# A wall-clock time in a named zone.
|
|
210
|
-
#
|
|
211
|
-
# @param timezone [Object] a +TZInfo::Timezone+
|
|
212
|
-
# @param civil [::Array<::Numeric>] year, month, day, hour, minute and
|
|
213
|
-
# seconds (with any fraction)
|
|
214
|
-
# @return [::Time] at the offset in force at that wall-clock time
|
|
215
|
-
# @raise [ArgumentError] when the zone skips that wall-clock time
|
|
216
|
-
def self.local(timezone, civil)
|
|
217
|
-
# tzinfo reads the components and ignores the offset of the Time it is
|
|
218
|
-
# given. In an overlap, dst = true and the block pick what
|
|
219
|
-
# ActiveSupport's TimeZone#period_for_local picks.
|
|
220
|
-
period = timezone.period_for_local(::Time.utc(*civil), true, &:last)
|
|
221
|
-
::Time.new(*civil, period.observed_utc_offset)
|
|
222
|
-
rescue ::TZInfo::PeriodNotFound
|
|
223
|
-
# The input is not echoed — see Types::Time#coerce. The zone is the
|
|
224
|
-
# declaration, not the value.
|
|
225
|
-
raise ArgumentError,
|
|
226
|
-
"names a local time that does not exist in #{timezone.identifier} (skipped by a daylight-saving change)"
|
|
227
|
-
end
|
|
228
|
-
|
|
229
|
-
# @param time [::Time] an instant
|
|
230
|
-
# @param timezone [Object] a +TZInfo::Timezone+
|
|
231
|
-
# @return [::Time] the same instant at the zone's offset at that instant
|
|
232
|
-
def self.in_zone(time, timezone)
|
|
233
|
-
time.getlocal(timezone.period_for(time).observed_utc_offset)
|
|
234
|
-
end
|
|
235
|
-
|
|
236
|
-
# @param value [::Date] a plain Date
|
|
237
|
-
# @param zone [::String] a declared +zone:+
|
|
238
|
-
# @return [::Time] midnight at +zone+'s offset — for a name, the first
|
|
239
|
-
# moment of that day
|
|
240
|
-
def self.midnight(value, zone)
|
|
241
|
-
offset = offset_seconds(zone)
|
|
242
|
-
return named_midnight(value, timezone(zone)) if offset.nil?
|
|
243
|
-
|
|
244
|
-
time = ::Time.new(value.year, value.mon, value.mday, 0, 0, 0, offset)
|
|
245
|
-
zone == 'UTC' ? time.utc : time
|
|
246
|
-
end
|
|
247
|
-
|
|
248
|
-
# @param value [::Date] a plain Date
|
|
249
|
-
# @param timezone [Object] a +TZInfo::Timezone+
|
|
250
|
-
# @return [::Time] the first moment of that day in the zone
|
|
251
|
-
def self.named_midnight(value, timezone)
|
|
252
|
-
local(timezone, [value.year, value.mon, value.mday, 0, 0, 0])
|
|
253
|
-
rescue ArgumentError
|
|
254
|
-
# The zone skips midnight: the day starts where the gap ends, the
|
|
255
|
-
# instant midnight would be at the offset in force just before it.
|
|
256
|
-
before = timezone.period_for_local(::Time.utc(value.year, value.mon, value.mday) - 1, true, &:last)
|
|
257
|
-
in_zone(::Time.utc(value.year, value.mon, value.mday) - before.observed_utc_offset, timezone)
|
|
258
|
-
end
|
|
259
|
-
|
|
260
|
-
# @param seconds [::Integer] seconds east of UTC
|
|
261
|
-
# @return [::String] +"+HH:MM"+ / +"-HH:MM"+
|
|
262
|
-
def self.offset_text(seconds)
|
|
263
|
-
format('%s%02d:%02d', seconds.negative? ? '-' : '+', seconds.abs / 3600, (seconds.abs % 3600) / 60)
|
|
264
|
-
end
|
|
265
|
-
end
|
|
266
|
-
end
|
|
267
|
-
end
|