How to add your own field type
Hut wardens write altitudes as '2,350 m', '2350m' or plain 2350. You want an Integer number of metres every time, and an error for anything else.
1. Write the type
Section titled “1. Write the type”Subclass FieldStruct::Types::Base and define coerce and ruby_type. Return nil for nil, and raise ArgumentError to refuse a value. Finish the keywords with **, because the setter hands over every option on the field.
class Altitude < FieldStruct::Types::Base def coerce(value, **) return nil if value.nil? return value if value.is_a?(Integer)
text = value.to_s.delete(',').strip.delete_suffix('m').strip raise ArgumentError, 'Altitude fields expect metres, like "2350 m"' unless text.match?(/\A\d+\z/)
Integer(text) end
def ruby_type = IntegerendThe message never repeats the value, the same way the built-in types word theirs.
2. Register it under a name
Section titled “2. Register it under a name”A module that answers field_types with a registry lends its names to every struct declared inside it. new_registry keeps the built-ins as its parent, so :string still works.
module Alpine def self.field_types @field_types ||= FieldStruct.new_registry { register :altitude, Altitude } end
class Pass < FieldStruct::Base required :name, :string required :height, :altitude endend
Alpine::Pass.new(name: 'Col Blanc', height: '2,350 m').height # => 2350Alpine::Pass.new(name: 'Col Blanc', height: 2350).height # => 2350If you only need the type in one place, skip the registry and pass the class itself: required :height, Altitude.
3. Read the error
Section titled “3. Read the error”A refused value is kept and recorded like any other coercion failure, with your message after the standard prefix.
pass = Alpine::Pass.new(name: 'Col Blanc', height: 'very high')pass.valid? # => falsepass.errors[:height] # => ["could not be coerced: Altitude fields expect metres, like \"2350 m\""]4. Give it an option
Section titled “4. Give it an option”Declare the option in own_option_schema and take it as a keyword in coerce. A wrong value type now raises when the class is declared, not when it runs.
class CappedAltitude < Altitude def self.own_option_schema {ceiling: option(type: [Integer])} end
def coerce(value, ceiling: nil, **) metres = super raise ArgumentError, "Altitude fields expect at most #{ceiling} m" if ceiling && metres && metres > ceiling
metres endend
class Hut < FieldStruct::Base required :height, CappedAltitude, ceiling: 4810end
Hut.new(height: '3,100 m').height # => 3100Hut.new(height: '5000 m').errors[:height] # => ["could not be coerced: Altitude fields expect at most 4810 m"]
begin Class.new(FieldStruct::Base) { required :height, CappedAltitude, ceiling: '4810' }rescue ArgumentError => e e.message # => 'ceiling: on CappedAltitude expects Integer, got String ("4810")'endSee also
Section titled “See also”- Registries and custom types, for
missing?,rbs_type, aliases and changing a built-in’s defaults - Types, to check a built-in doesn’t already read your value
- Validation and errors, for the coercion policies
FieldStruct, Actionable and their adapters are open source under the MIT license.