Validation and errors
A field setter coerces the value, stores it, and validates that one field. Problems go onto obj.errors and aren’t raised unless you ask for :raise. Building an object and asking whether it is valid are two different things: new always hands back an instance, and valid? reports the outcome.
The macros that set policies live on Class macros.
The setter pipeline
Section titled “The setter pipeline”name=(value) runs these steps in order, and new, assign_attributes and with run the same ones for every key.
- If the instance is initialized and the class is
immutable!, raiseImmutableError. - Coerce with the field’s type. A failure (
ArgumentError,TypeErrororRangeError) is handed to the coercion policy and the pipeline stops. - Store the coerced value.
- Validate the field (below).
Any other exception, like NoMethodError or a FieldStruct::Error, propagates. The setter returns the coerced value. Assigning a field again reruns the whole pipeline and rewrites that field’s errors while leaving the other fields’ errors alone. Under :keep_raw, a later good value clears an earlier coercion error.
Field validation
Section titled “Field validation”Once coercion succeeds, validation goes in this order and stops at the first step that applies:
- Clear that field’s errors.
- If the type calls the value missing, add
"is required"when the field is required and stop. A missing optional value is fine, and so is a givennilon a field declarednullable: true. - Otherwise, when a string-family value is outside its
length:, or an array holds more than itsmax_items:, add that size message and stop. - Otherwise, when the value fails
format:(a Regexp only),enum:orin:, or is an invalid nested struct or holds one, add"is invalid". It is added once, however many checks fail. - For an array with
element:options, add the element-index message, and for a map with them the entry-count message (see Types).
| Message | When |
|---|---|
"is required" |
a required field is missing: nil, a blank String, an empty Array or Hash |
"is too short (minimum is 3)", "is too long (maximum is 40)" |
a string-family value is outside its length: |
"is invalid" |
format:, enum: or in: failed, or a nested struct inside is invalid |
"element at index 1 is invalid" |
an element of an array failed an element: check |
"1 entry is invalid", "2 entries are invalid" |
values of a map failed an element: check; the message names no key |
"has too many items (maximum is 3)" |
an array holds more elements than its max_items: |
"could not be coerced: <reason>" |
the type couldn’t read the value |
| anything you add | from validate or errors.add |
format:, enum: and in: can be combined, and any failure gives a single "is invalid". nil never fails them. A Symbol or String format: (temporal presets and strftime strings) only drives parsing and adds no error. Coercion goes first, so '10' is already 10 when in: looks at it.
length: takes a Range of whole numbers (3..40, ..40, 3..) and counts characters, or bytes on :binary. It runs before format: and enum:, and a value that breaks it gets only the length message, which names the limit and never the value. A blank String is missing, so it skips length: the way it skips every check: '' passes length: 3.. on an optional field, and is "is required" on a required one.
class Burrow < FieldStruct::Base required :name, :string, length: 3..12 optional :entrance, :string, length: 2..end
Burrow.new(name: 'Ox').errors[:name] # => ["is too short (minimum is 3)"]Burrow.new(name: 'Underhill-East').errors[:name] # => ["is too long (maximum is 12)"]Burrow.new(name: 'Sett', entrance: '').valid? # => trueWhen coercion fails on a required field, only the coercion error is recorded, never "is required" as well, even if :replace stored nil. Defaults satisfy required, because the check looks at the stored value.
Messages carry the class of the input, never the value. That covers coercion errors, CoercionError, union and array messages, from_json errors and the cause chain, so it is safe to log them. Custom types write their own messages, and those should name the class as well.
class Seedling < FieldStruct::Base required :tag, :string, format: /\A[A-Z]{2}-\d+\z/ optional :count, :integer, in: 1..40 optional :stage, :symbol, enum: %i[sprout potted hardened]end
seedling = Seedling.new(tag: 'zz', count: 'a dozen')seedling.valid? # => falseseedling.errors[:tag] # => ["is invalid"]seedling.errors[:count].first.start_with?('could not be coerced') # => trueseedling.errors.full_messages.first # => "Tag is invalid"Seedling.new.errors[:tag] # => ["is required"]Seedling.new(tag: 'FE-7', count: 400).errors[:count] # => ["is invalid"]Seedling.new(tag: 'FE-7', count: nil, stage: nil).valid? # => trueValidity is computed on assignment
Section titled “Validity is computed on assignment”valid? runs the cross-field validators when the class has any, then reports errors.empty?. invalid? says the opposite. Per-field errors are set at assignment and never recomputed afterwards. Changing a nested struct, or an element of an array, in place doesn’t refresh the parent in either direction, and pushing onto an array in place stores the raw element without coercion. To rerun coercion and validation, assign the field again or use with or assign_attributes.
An invalid nested struct gives the parent field "is invalid" when it is assigned. So does an Array containing at least one invalid struct, and so does a bare struct assigned to a :value field. Only the value itself and the elements of an Array are inspected, so a struct inside a Hash value goes unchecked.
class Tray < FieldStruct::Base required :cells, :integerend
class Nursery < FieldStruct::Base optional :tray, Trayend
nursery = Nursery.new(tray: {cells: 24})nursery.valid? # => truenursery.tray.cells = 'plenty'nursery.valid? # => truenursery.tray = nursery.traynursery.errors[:tray] # => ["is invalid"]
seedling = Seedling.new(tag: 'zz')seedling.tag = 'FE-7'seedling.valid? # => trueCoercion failure policy
Section titled “Coercion failure policy”When a type refuses a value, the policy in force is the field’s coercion_policy: if it has one, otherwise the class’s, which defaults to :keep_raw.
| Policy | What happens |
|---|---|
:keep_raw |
the raw input is stored and a single "could not be coerced: ..." message is recorded |
:replace |
the field becomes nil and the same message is recorded |
:raise |
the setter raises FieldStruct::CoercionError and the old value stays |
:keep_raw and :replace skip the validation steps, so the coercion message never comes with "is required" or "is invalid". An invalid object under :keep_raw can thus hold a value of the wrong class, so check valid? before trusting a value.
For arrays, a single refused element fails the whole array under the policy. The message lists zero-based indexes, never values: element at index 1: <reason>, or elements at index 1, 4 (index 1 shown): <reason>, with at most five indexes before and N more.
CoercionError has field_name (a Symbol) and original, the coercion exception, which is also its cause. The message reads could not coerce Integer input for fruit: <reason>. A field-level coercion_policy: is inherited along with the field, and a subclass that redeclares the field without it loses the override.
class Trial < FieldStruct::Base optional :sprouts, :integer optional :buds, :integer, coercion_policy: :replace optional :fruit, :integer, coercion_policy: :raise required :stems, :integer, coercion_policy: :replaceend
trial = Trial.new(sprouts: 'few', buds: 'many', stems: 'tall')trial.sprouts # => "few"trial.buds # => niltrial.errors[:stems].size # => 1trial.errors[:stems].first.start_with?('could not be coerced:') # => true
begin Trial.new(fruit: 'ripe')rescue FieldStruct::CoercionError => e e.field_name # => :fruit e.original.class # => ArgumentError e.message.start_with?('could not coerce String input for fruit:') # => trueendCross-field validation
Section titled “Cross-field validation”validate takes method names, which are called on the record with no arguments, or a block, which is called with the record. Every name and every block is a validator of its own. You can mix the two forms and stack calls, and validators run in declaration order. validate returns the class.
Validators run after the per-field checks: once at the end of new and with (only when the class declares any), and again on every valid?. errors[:base] is cleared before each run, so cross-field messages belong under :base. Per-field errors are left alone, which means a validator writing to a named field must clean that entry up itself. A subclass gets a copy of its parent’s validators and adds its own. An inherited one can’t be removed.
Validators have to cope with nil fields, since the record may be invalid. The library doesn’t guard against an exception raised inside a validator. assign_attributes doesn’t rerun validators, but valid? does.
class Band < FieldStruct::Base required :coldest, :integer required :warmest, :integer validate :ordered validate { |band| band.errors.add(:base, 'no variation') if band.coldest == 0 && band.warmest == 0 }
def ordered errors.add(:base, 'warmest must exceed coldest') if coldest && warmest && warmest <= coldest endend
Band.new(coldest: 9, warmest: 4).errors[:base] # => ["warmest must exceed coldest"]Band.new(coldest: 0, warmest: 0).errors[:base] # => ["warmest must exceed coldest", "no variation"]Band.new(coldest: -2, warmest: 11).valid? # => true
band = Band.new(coldest: -2, warmest: 11)band.warmest = -5band.errors[:base] # => []band.valid? # => falseband.errors[:base] # => ["warmest must exceed coldest"]The Errors API
Section titled “The Errors API”obj.errors is a FieldStruct::Errors, a plain value object that doesn’t depend on ActiveModel. Keys are Symbols, though a String key works anywhere you read one.
| Member | Returns |
|---|---|
#[](field) |
the field’s messages, or a throwaway [] that is not stored |
#add(field, message) |
appends a message, creating the entry if needed |
#clear(field) |
removes the field’s entry and returns nil |
#empty? |
true when no field has a message |
#to_h, #messages |
{field => [messages]} for fields that have messages, a new Hash on each call, ordered by when each field first got a message |
#paths |
{"slats[1].width" => ["is required"]}: where each message comes from, nested structs included. See below |
#full_messages |
"Name is required": the humanized field name, a space, the message. :base gets no prefix |
#inspect |
#<FieldStruct::Errors empty> or #<FieldStruct::Errors name=["is required"]> |
#freeze |
freezes the message arrays too, so add and clear raise FrozenError |
dup, clone |
a deep copy of the message arrays; a dup of frozen errors can be changed again |
Humanizing swaps underscores for spaces and upcases the first character, nothing more. The inspect prefix follows use_alias!.
Error keys appear in this order: first those from the defaults pass, in declaration order, then those from the input, in input order. Take three required fields genus, species and cultivar and the input {cultivar: nil, genus: nil}: the keys are [:species, :cultivar, :genus].
errors = FieldStruct::Errors.newerrors.empty? # => trueerrors.add(:leaf_color, 'is required')errors.add(:base, 'Needs a second look')errors['leaf_color'] # => ["is required"]errors.full_messages # => ["Leaf color is required", "Needs a second look"]errors.to_h # => {leaf_color: ["is required"], base: ["Needs a second look"]}errors.inspect # => '#<FieldStruct::Errors leaf_color=["is required"] base=["Needs a second look"]>'copy = errors.dupcopy.clear(:leaf_color)errors.empty? # => falseerrors[:missing] # => []
class Label < FieldStruct::Base required :genus, :string required :species, :string required :cultivar, :stringend
Label.new(cultivar: nil, genus: nil).errors.to_h.keys # => [:species, :cultivar, :genus]Once an instance’s errors are frozen, valid? reads them as they are and runs no validator, since a validator could no longer record anything. The errors on a frozen Actionable result are frozen this way.
class Hedge < FieldStruct::Base required :species, :stringend
hedge = Hedge.new(species: nil)hedge.errors.freezehedge.valid? # => falsebegin hedge.errors.add(:species, 'try again')rescue FrozenError hedge.errors[:species] # => ["is required"]endhedge.dup.errors.frozen? # => falsePaths into nested structs
Section titled “Paths into nested structs”An invalid nested struct shows in to_h as one "is invalid" on the parent field. paths says which part was wrong: a nested field adds .name, an array element adds [index], a map value adds {"key"}, and a top-level field is just its name. to_h doesn’t change.
class Slat < FieldStruct::Base required :width, :integerend
class Trellis < FieldStruct::Base required :bed, :string optional :slats, :array, of: Slatend
trellis = Trellis.new(bed: 'east', slats: [{ width: 4 }, {}])trellis.errors.to_h # => {slats: ["is invalid"]}trellis.errors.paths # => {"slats[1].width" => ["is required"]}Trellis.new(slats: []).errors.paths # => {"bed" => ["is required"]}
class Arbor < FieldStruct::Base optional :slats_by_side, :hash, of: Slatend
Arbor.new(slats_by_side: { north: { width: 3 }, south: {} }).errors.paths# => {"slats_by_side{\"south\"}.width" => ["is required"]}paths reads the nested structs as they are when you call it and runs no validators. If you fix a nested struct in place, the parent still says "is invalid" (validity is computed on assignment), and since no child explains it any more, paths keeps the parent’s own entry. A failed :invalid_input run in Actionable answers paths for its input the same way.
Errors in inspect
Section titled “Errors in inspect”When there are errors, inspect appends them as errors: {field: ["message"]}. It reads them as they stand and never reruns validation or validators. Sensitive values can’t show up, since messages hold no values. See Instance API.
Seedling.new(tag: 'zz').inspect # => '#<Seedling tag: "zz", count: nil, stage: nil errors: {tag: ["is invalid"]}>'See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.