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
|
@@ -1,85 +1,75 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
module FieldStruct
|
|
4
|
-
#
|
|
5
|
-
#
|
|
6
|
-
# Holds the resolution table that maps symbolic type names (`:string`,
|
|
7
|
-
# `:integer`, …) to the {Types} classes that implement them. A namespace
|
|
8
|
-
# can build its own registry parented to the base ({FieldStruct.types})
|
|
9
|
-
# to extend or override the default set without mutating it.
|
|
4
|
+
# Maps type names (Symbols) to type classes, with an optional parent to fall back to.
|
|
10
5
|
class Registry
|
|
11
|
-
# @return [Registry, nil]
|
|
6
|
+
# @return [FieldStruct::Registry, nil]
|
|
12
7
|
attr_reader :parent
|
|
13
8
|
|
|
14
|
-
# @param parent [Registry, nil]
|
|
15
|
-
# isn't found locally
|
|
9
|
+
# @param parent [FieldStruct::Registry, nil]
|
|
16
10
|
def initialize(parent = nil)
|
|
17
11
|
@parent = parent
|
|
18
|
-
@
|
|
12
|
+
@entries = {}
|
|
19
13
|
end
|
|
20
14
|
|
|
21
|
-
#
|
|
15
|
+
# Registers a type class, or an alias to an already registered name.
|
|
16
|
+
# An alias is resolved now, so re-registering its target later does not move it.
|
|
22
17
|
#
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
#
|
|
26
|
-
# Aliases are eagerly resolved through {#lookup}, so the alias target
|
|
27
|
-
# must already be registered (locally or in a parent). A later
|
|
28
|
-
# registration of the same name overwrites silently — this is the
|
|
29
|
-
# mechanism that lets a namespace registry shadow a parent's type.
|
|
30
|
-
#
|
|
31
|
-
# @param name [Symbol, String] the name to register
|
|
32
|
-
# @param target [Class, Symbol] a type class, or an existing registered name
|
|
18
|
+
# @param name [Symbol, String]
|
|
19
|
+
# @param target [Class, Symbol, String] a type class, or the name to alias
|
|
33
20
|
# @return [self]
|
|
34
|
-
# @raise [KeyError] when
|
|
21
|
+
# @raise [KeyError] when an alias target is unknown
|
|
35
22
|
def register(name, target)
|
|
36
|
-
|
|
37
|
-
@types[name.to_sym] = type_class
|
|
23
|
+
@entries[name.to_sym] = target.is_a?(Class) ? target : lookup(target)
|
|
38
24
|
self
|
|
39
25
|
end
|
|
40
26
|
|
|
41
|
-
# Resolve a name to its type class, walking the parent chain.
|
|
42
|
-
#
|
|
43
27
|
# @param name [Symbol, String]
|
|
44
|
-
# @return [Class]
|
|
45
|
-
# @raise [KeyError] when
|
|
28
|
+
# @return [Class]
|
|
29
|
+
# @raise [KeyError] when no registry in the chain knows the name
|
|
46
30
|
def lookup(name)
|
|
47
31
|
key = name.to_sym
|
|
48
|
-
return @
|
|
49
|
-
return @parent.lookup(key) if @parent
|
|
32
|
+
return @entries[key] if @entries.key?(key)
|
|
33
|
+
return @parent.lookup(key) if @parent&.key?(key)
|
|
34
|
+
|
|
35
|
+
raise KeyError, "no FieldStruct type registered for #{key.inspect}#{Suggestion.clause(key, names)}"
|
|
36
|
+
end
|
|
50
37
|
|
|
51
|
-
|
|
38
|
+
# Every name resolvable here, own first, then the parent's, each once.
|
|
39
|
+
# @api private
|
|
40
|
+
#
|
|
41
|
+
# @return [Array<Symbol>]
|
|
42
|
+
def names
|
|
43
|
+
(@entries.keys + (@parent ? @parent.names : [])).uniq
|
|
52
44
|
end
|
|
53
45
|
|
|
54
|
-
#
|
|
46
|
+
# The first name (in chain order) whose type has the same short class name as +klass+, e.g. +:string+ for String.
|
|
47
|
+
# @api private
|
|
55
48
|
#
|
|
49
|
+
# @param klass [Class] a class given as a type that is not one
|
|
50
|
+
# @return [Symbol, nil]
|
|
51
|
+
def name_for_lookalike(klass)
|
|
52
|
+
short = klass.name.to_s.split('::').last
|
|
53
|
+
return nil if short.nil? || short.empty?
|
|
54
|
+
|
|
55
|
+
names.find { |name| lookup(name).name.to_s.split('::').last == short }
|
|
56
|
+
end
|
|
57
|
+
|
|
56
58
|
# @param name [Symbol, String]
|
|
57
|
-
# @return [Boolean]
|
|
59
|
+
# @return [Boolean] whether this registry or an ancestor knows the name
|
|
58
60
|
def key?(name)
|
|
59
61
|
key = name.to_sym
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
!@parent.nil? && @parent.key?(key)
|
|
62
|
+
@entries.key?(key) || (@parent ? @parent.key?(key) : false)
|
|
63
63
|
end
|
|
64
64
|
|
|
65
|
-
#
|
|
66
|
-
# those inherited from the parent chain. Local entries come first;
|
|
67
|
-
# duplicates (e.g. an alias pointing at an already-listed class, or a
|
|
68
|
-
# parent class also registered locally) are removed.
|
|
69
|
-
#
|
|
70
|
-
# @return [Array<Class>] deduplicated, local-first
|
|
65
|
+
# @return [Array<Class>] distinct classes resolvable here: own first, then the parent's
|
|
71
66
|
def type_classes
|
|
72
|
-
|
|
73
|
-
(@parent ? own + @parent.type_classes : own).uniq
|
|
67
|
+
(@entries.values + (@parent ? @parent.type_classes : [])).uniq
|
|
74
68
|
end
|
|
75
69
|
|
|
76
|
-
# @return [String]
|
|
77
|
-
# (does not enumerate the parent chain), with a +parent+ marker
|
|
78
|
-
# when the registry has one
|
|
70
|
+
# @return [String]
|
|
79
71
|
def inspect
|
|
80
|
-
|
|
81
|
-
parts << 'parent' if @parent
|
|
82
|
-
"#<#{FieldStruct.inspect_namespace}::Registry #{parts.join(" ")}>"
|
|
72
|
+
"#<#{FieldStruct.inspect_namespace}::Registry types=#{@entries.keys.inspect}#{' parent' if @parent}>"
|
|
83
73
|
end
|
|
84
74
|
end
|
|
85
75
|
end
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module FieldStruct
|
|
4
|
+
# The value checks a field's +format:+ (Regexp), +enum:+, +in:+ and +length:+ options describe.
|
|
5
|
+
module Restrictions
|
|
6
|
+
# The one message a broken restriction gives: the +length:+ message wins (FS-B37a), else +"is invalid"+.
|
|
7
|
+
#
|
|
8
|
+
# @param value [Object] an already coerced value
|
|
9
|
+
# @param options [Hash{Symbol=>Object}] the field's (or element's) options
|
|
10
|
+
# @return [String, nil] +nil+ when nothing is broken; +nil+ never breaks a restriction
|
|
11
|
+
def self.problem(value, options)
|
|
12
|
+
return nil if value.nil?
|
|
13
|
+
|
|
14
|
+
too = size_message(value, options)
|
|
15
|
+
too || ('is invalid' if format_broken?(value, options[:format]) || enum_broken?(value, options[:enum]) ||
|
|
16
|
+
range_broken?(value, options[:in]))
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# The specific message for a value outside its +length:+ bounds (FS-B37a). It names the declared limit, never the value.
|
|
20
|
+
#
|
|
21
|
+
# @param value [String] an already coerced value
|
|
22
|
+
# @param bounds [Range, nil] the field's +length:+
|
|
23
|
+
# @return [String, nil] +nil+ when there is no bound or the value is within it
|
|
24
|
+
# +length:+ on a String, +max_items:+ on an Array (FS-B168), or nil.
|
|
25
|
+
def self.size_message(value, options)
|
|
26
|
+
return length_message(value, options[:length]) if value.is_a?(::String)
|
|
27
|
+
|
|
28
|
+
limit = options[:max_items]
|
|
29
|
+
"has too many items (maximum is #{limit})" if limit && value.is_a?(::Array) && value.size > limit
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
def self.length_message(value, bounds)
|
|
33
|
+
return nil if bounds.nil?
|
|
34
|
+
|
|
35
|
+
size = value.length
|
|
36
|
+
min = bounds.begin
|
|
37
|
+
return "is too short (minimum is #{min})" if min && size < min
|
|
38
|
+
|
|
39
|
+
max = length_max(bounds)
|
|
40
|
+
"is too long (maximum is #{max})" if max && size > max
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# @param bounds [Range]
|
|
44
|
+
# @return [Boolean] whether each end is an Integer >= 0 or nil, at least one is set, and the Range is not empty
|
|
45
|
+
def self.usable_length?(bounds)
|
|
46
|
+
return false unless whole_ends?(bounds)
|
|
47
|
+
|
|
48
|
+
max = length_max(bounds)
|
|
49
|
+
bounds.begin.nil? || max.nil? || bounds.begin <= max
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
# @param bounds [Range]
|
|
53
|
+
# @return [Boolean] each end is an Integer >= 0 or nil, and at least one is set
|
|
54
|
+
def self.whole_ends?(bounds)
|
|
55
|
+
ends = [bounds.begin, bounds.end]
|
|
56
|
+
ends.all? { |n| n.nil? || (n.is_a?(::Integer) && n >= 0) } && ends.any?
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# @param bounds [Range]
|
|
60
|
+
# @return [Integer, nil] the largest allowed length; an exclusive end allows one less
|
|
61
|
+
def self.length_max(bounds)
|
|
62
|
+
last = bounds.end
|
|
63
|
+
last && bounds.exclude_end? ? last - 1 : last
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
def self.format_broken?(value, format)
|
|
67
|
+
format.is_a?(::Regexp) && !format.match?(value.to_s)
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
def self.enum_broken?(value, enum)
|
|
71
|
+
!enum.nil? && !enum.include?(value)
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
def self.range_broken?(value, bounds)
|
|
75
|
+
return false if bounds.nil?
|
|
76
|
+
|
|
77
|
+
bounds.is_a?(::Range) ? !bounds.cover?(comparable(value, bounds)) : !bounds.include?(value)
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
# A DateTime compared with plain Date endpoints counts as its calendar date, so 15:00 on the last day is inside.
|
|
81
|
+
def self.comparable(value, range)
|
|
82
|
+
return value unless value.is_a?(::DateTime)
|
|
83
|
+
|
|
84
|
+
plain_date = ->(endpoint) { endpoint.is_a?(::Date) && !endpoint.is_a?(::DateTime) }
|
|
85
|
+
plain_date.call(range.begin) || plain_date.call(range.end) ? ::Date.new(value.year, value.mon, value.mday) : value
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
private_class_method :format_broken?, :enum_broken?, :range_broken?, :comparable, :length_max, :whole_ends?
|
|
89
|
+
end
|
|
90
|
+
end
|