A typed Hut
We start with the smallest piece of the hut network: one hut. By the end of this chapter we’ll have a Hut that takes string input from a form, turns it into real Ruby values, and tells us what is wrong when it can’t.
Where we left off
Section titled “Where we left off”Nothing yet. This is the first chapter and it needs only field_struct, so open irb with require 'field_struct' or put the code in a script.
Declare the fields
Section titled “Declare the fields”A struct is a class that inherits from FieldStruct::Base. Every field has a name and a type, and it is either required or optional.
class Hut < FieldStruct::Base required :name, :string optional :places, :integerend
hut = Hut.new(name: 'Larch Col', places: 24)hut.name # => "Larch Col"hut.valid? # => truerequired means the field has to be present for the hut to be valid. It doesn’t stop you from building a hut without it, as we’ll see in a moment.
Coerce strings
Section titled “Coerce strings”Form and query params arrive as strings, and assigning a string to an :integer field converts it.
form = { name: 'Larch Col', places: '24' }Hut.new(**form).places # => 24The conversion runs on every assignment, in new and in the setters, so hut.places = '30' leaves 30 behind.
Add a code, a distance and a season
Section titled “Add a code, a distance and a season”A distance in kilometres is a measurement, so we use :decimal. A float would hand us the 0.1 + 0.2 problem. Four options earn their place here:
format:checks a string against a patternround:rounds a number to that many decimal placesin:limits a number to a rangedefault:fills in a value when none is given
The season is a :symbol limited to a list with enum:.
class Hut < FieldStruct::Base required :name, :string required :code, :string, format: /\A[A-Z]{2}\d{2}\z/ required :distance_km, :decimal, round: 1 optional :places, :integer, in: 1..400 optional :season, :symbol, enum: %i[summer winter year_round] optional :altitude, :integer, in: 0.., default: 0endNow a hut built from the strings a form would send.
hut = Hut.new( name: 'Larch Col', code: 'KR12', distance_km: '7.25', places: '24', season: 'summer')
hut.distance_km # => BigDecimal('7.3')hut.places # => 24hut.season # => :summerhut.altitude # => 0hut.valid? # => trueThe distance 7.25 rounded to 7.3, 'summer' became the symbol :summer, and altitude took its default.
Read the errors
Section titled “Read the errors”Now we feed it bad input.
bad = Hut.new(name: ' ', code: 'k1', distance_km: '3.5', places: 9_000, season: 'monsoon')
bad.valid? # => falsebad.errors.full_messages.size # => 4errors.full_messages gives one sentence per problem: the blank name, the malformed code, the place count outside 1..400 and the season missing from the list. Nothing raised. Building a hut is never the same as validating it.
For one field at a time, use errors.to_h.
bad.errors.to_h[:name] # => ["is required"]bad.errors.to_h[:places] # => ["is invalid"]bad.errors.to_h.keys # => [:name, :code, :places, :season]A blank string counts as missing, which is why the name reads “is required” and not “is invalid”.
When a value can’t be coerced
Section titled “When a value can’t be coerced”What if places is 'plenty'? There is no integer to make out of that.
odd = Hut.new(name: 'Larch Col', code: 'KR12', distance_km: '3.5', places: 'plenty')
odd.places # => "plenty"odd.valid? # => falseodd.errors.to_h[:places].size # => 1By default the raw value stays in the field and the error is recorded. The object remains usable, and your code decides whether to show the error, ask again or give up. The messages never echo what was typed.
If you’d rather have an exception, a class can ask for it with coercion_policy :raise. We keep the default for the hut network.
What you built
Section titled “What you built”A Hut with required and optional fields, four types (:string, :decimal, :integer, :symbol) with the options format:, round:, in:, enum: and default:, string coercion, and an errors object that reports problems without raising.
Next we’ll put huts into bookings and send them as JSON.
See also
Section titled “See also”- Bookings and JSON: the next chapter
- Fields and options
- Types
- Coercion versus validation
FieldStruct, Actionable and their adapters are open source under the MIT license.