Exceptions
FieldStruct has only three exception classes of its own. Bad input is normally recorded on errors, not raised, and the three classes below are for the cases where raising is the whole point. Everything else is a standard Ruby error whose message is a full sentence and never includes an input value.
StandardError FieldStruct::Error FieldStruct::CoercionError #field_name, #original FieldStruct::ImmutableError FieldStruct::UnknownAttributeError #keysOne rescue FieldStruct::Error catches all three.
FieldStruct::CoercionError
Section titled “FieldStruct::CoercionError”A setter raises it when a type can’t read a value and the effective coercion policy is :raise. The previous value stays in place.
| Reader | Value |
|---|---|
message |
could not coerce <InputClass> input for <field>: <reason> |
field_name |
the field, as a Symbol |
original |
the exception the type raised. It is also the cause |
Through new, assign_attributes and with, the first bad key raises. For arrays the message includes an index phrase like element at index 1: .... The reason names classes, never values.
class Anemometer < FieldStruct::Base coercion_policy :raise required :gust_kph, :float optional :calibrated_on, :dateend
begin Anemometer.new(gust_kph: 'breezy')rescue FieldStruct::CoercionError => e e.field_name # => :gust_kph e.original.class # => ArgumentError e.cause.equal?(e.original) # => true e.message.start_with?('could not coerce String input for gust_kph:') # => trueend
vane = Anemometer.new(gust_kph: 35)begin vane.calibrated_on = 'last spring'rescue FieldStruct::CoercionError => e e.field_name # => :calibrated_onendvane.calibrated_on # => nilFieldStruct::ImmutableError
Section titled “FieldStruct::ImmutableError”Any setter, and assign_attributes, raises it on an instance of an immutable! class after new has finished, before any coercion happens. The message is <Class> is immutable; cannot reassign <field>, and an anonymous class prints as #<Class:0x...>.
class Benchmark < FieldStruct::Base immutable! required :elevation_m, :integerend
begin Benchmark.new(elevation_m: 120).assign_attributes(elevation_m: 125)rescue FieldStruct::ImmutableError => e e.message # => "Benchmark is immutable; cannot reassign elevation_m"endFieldStruct::UnknownAttributeError
Section titled “FieldStruct::UnknownAttributeError”new, assign_attributes and with raise it on a class declared with unknown_attributes :raise, before anything is assigned. keys holds the unknown keys as Symbols in input order, and the message reads unknown attribute(s) for <Class>: :a, :b.
class Seedbed < FieldStruct::Base unknown_attributes :raise required :label, :stringend
begin Seedbed.new(label: 'north', soil: 'clay', shade: 2)rescue FieldStruct::UnknownAttributeError => e e.keys # => [:soil, :shade] e.message # => "unknown attribute(s) for Seedbed: :soil, :shade"endRuby exceptions
Section titled “Ruby exceptions”| Class | When |
|---|---|
ArgumentError |
new or assign_attributes given something other than a Hash or to_hash object; with given a positional argument; a declaration problem (bad option value, an option on the wrong type, a reserved name, a bad zone:, an unknown preset); an unknown class macro value; from_json given a root that is not an object; the RBS and Scaffold helpers given bad input; serialize naming an undeclared field; a mirror that can’t read its source; partial or register_option refusing (below) |
KeyError |
an unknown type name, at declaration |
NameError |
use_alias! when the constant already exists and is something else |
FrozenError |
a setter on an instance made with frozen! |
NotImplementedError |
a custom type without coerce or ruby_type |
EncodingError |
from_json given malformed JSON. This is the class Oj raises, and FieldStruct defines none of its own |
Declaration problems raise while the class body runs, never at first use, so a typo in a type name or an option value fails at load time. That includes a misspelled option key: requird: true raises unknown option requird: ... (did you mean required:?). The declaration messages are listed on Fields and options.
A few of those ArgumentError messages, from the call or declaration that raises them:
| Situation | Message |
|---|---|
a mirror! class reads an object that lacks a public reader for one of its fields |
LampView mirrors Bulb, but Bulb has no public reader for :watts |
an array of mirrors reads a lazy collection (one that answers first) and has no max_items: |
set max_items: on Hall#lamps, or load the relation yourself |
Klass.partial when Klass::Partial is already defined |
Kiosk::Partial is already defined; Kiosk.partial would replace it |
FieldStruct.register_option for a name registered with another type: or owner: |
catalog: is already registered by atlas_app (type Hash); register it again only with the same type: and owner: |
FieldStruct.register_option for a built-in option |
default: is a universal field option, so it can't be registered, or length: is a native option of String, ... |
| an unknown option key | unknown option defualt: on field :slot (did you mean default:?) |
an adapter’s key before its require |
unknown option avro: on Booth#slot; avro: is registered by field_struct-avro, so require 'field_struct/avro' before declaring the field |
The messages from new and with name the class and the class of the input, never its value:
begin Seedbed.new(%w[north south])rescue ArgumentError => e e.message # => "Seedbed.new expects a Hash (or an object responding to #to_hash), got Array"end
begin Class.new(FieldStruct::Base) { required :species, :stirng }rescue KeyError => e e.message # => "no FieldStruct type registered for :stirng (did you mean :string?)"end
begin Seedbed.new(label: 'east').freeze.label = 'west'rescue FrozenError :frozen # => :frozenendWhat does not raise
Section titled “What does not raise”Each of these lands on errors and leaves the object usable:
- a missing required field:
"is required" - a failed
format:,enum:orin::"is invalid" - a value a type cannot read under
:keep_rawor:replace:"could not be coerced: ..." - a failed cross-field validator
Exceptions from your own validators or from a callable default propagate unchanged. So do errors raised while building a nested struct (UnknownAttributeError, CoercionError, ArgumentError): they come through as they are, and the parent’s policy doesn’t handle them.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.