Instance API
An instance of a FieldStruct::Base subclass is an ordinary Ruby object with a reader and a writer for each field. This page covers every call you can make on it, in the order they come up: build, read, change, copy, compare, print.
Validity and errors have their own page, Validation and errors.
| Member | Returns |
|---|---|
.new(attrs = {}) |
an instance, always, even when the input is invalid |
#assign_attributes(attrs) |
self |
#with(**changes) |
a new instance, the receiver is untouched |
#<name>, #<name>= |
the field’s reader, and a coercing writer |
#attributes, #to_h |
a fresh Hash with Symbol keys, in declaration order |
#attribute_names |
the field names, also available on the class |
#errors, #valid?, #invalid? |
the Errors object, and validity |
#==, #eql?, #hash |
equality by class and attributes |
#dup, #clone |
a shallow copy that owns a copy of the errors |
#inspect |
#<Name field: value, ...> |
#deconstruct, #deconstruct_keys |
pattern matching |
#model_name, #to_model |
naming helpers |
#as_json, #to_json |
see JSON and serialization |
Klass.new(attrs = {})new accepts a Hash or anything that responds to to_hash, and treats nil as an empty Hash. Symbol and String keys address the same field, and when both 'a' and :a appear, the later one in hash order wins. Any other input raises ArgumentError. The message names the class and the input’s class, never the value:
Seedling.new expects a Hash (or an object responding to #to_hash), got ArrayConstruction goes through these steps:
- An empty
Errorsis created. - Under
unknown_attributes :raise, unknown keys are checked first, before any default runs. - The defaults pass runs each field’s setter with its default, in declaration order. A field with a
nildefault whose key is in the input is set straight tonil. assign_attributes(input)calls the setter of each known key, in input order.- Cross-field validators run, when the class has any.
- The instance is marked initialized, and that is what switches
immutable!on. - The instance is frozen when the class uses
frozen!.
A field left out is nil or its default, and a required field left out gets "is required". A callable default runs once for each instance. Errors raised while building a nested struct travel up unchanged.
class Seedling < FieldStruct::Base required :species, :string optional :count, :integer, default: 1end
Seedling.new(species: 'Fern').attributes # => {species: "Fern", count: 1}Seedling.new('species' => 'Fern', 'count' => '3').count # => 3Seedling.new(nil).species # => nilSeedling.new(nil).valid? # => false
mapish = Object.newdef mapish.to_hash = {species: 'Moss'}Seedling.new(mapish).species # => "Moss"
begin Seedling.new([])rescue ArgumentError => e e.message # => "Seedling.new expects a Hash (or an object responding to #to_hash), got Array"endReaders, writers and attributes
Section titled “Readers, writers and attributes”Every field gets a reader with its name and a writer name=. The writer is permissive: seedling.count = '30' stores 30, and a value it cannot read follows the coercion policy.
attributes and to_h are one and the same: a fresh Hash with Symbol keys in declaration order. The keys are always the Ruby field names, even when serialize maps them elsewhere. attribute_names gives a new Array of names, on the class and on an instance, and unknown input keys never add to it.
given_fields
Section titled “given_fields”given_fields lists the fields the caller gave, as a frozen Array in declaration order: keys in the input to new, assign_attributes, with or from_json, and fields set through a writer. Defaults never count, and neither do unknown keys. It tells “sent as null” apart from “not sent”, which a PATCH body needs.
class Cutting < FieldStruct::Base required :variety, :string optional :tray, :string, default: 'A1' optional :note, :stringend
sprout = Cutting.new(variety: 'basil', note: nil)sprout.given_fields # => [:variety, :note]sprout.given_fields.include?(:note) && sprout.note.nil? # => truesprout.given_fields.include?(:tray) # => falsesprout.with(tray: 'B2').given_fields # => [:variety, :tray, :note]It takes no part in ==, attributes or as_json.
assign_attributes
Section titled “assign_attributes”instance.assign_attributes(hash) # => instanceEach known key goes through the full setter pipeline, so coercion, the field’s policy and error rewriting all apply. The method returns self and leaves fields you did not mention alone. It does not rerun defaults or cross-field validators, and on an immutable! instance it raises ImmutableError. Unknown keys follow unknown_attributes. Unlike new, assign_attributes(nil) raises: ArgumentError: Seedling#assign_attributes expects a Hash (or an object responding to #to_hash), got NilClass.
instance.with(**changes) # => a new instanceThe result is a new instance of the receiver’s own class (subclasses are safe), with the changes applied through the full setter pipeline. It works on an immutable! instance as well, and the copy is immutable too. Fields you leave unchanged carry their errors over the way dup does. Cross-field validators run again, callable defaults do not, and the copy is frozen if the receiver was. Called with no changes it returns an equal copy, never self.
A positional argument raises: with({count: 1}) fails with Seedling#with takes keyword arguments only, got 1 positional; pass a Hash as with(**hash), while with(**hash) works, and so do String keys. Under :raise a bad value raises and no copy comes back.
sprout = Seedling.new(species: 'Fern', count: 2)copy = sprout.with(count: '5')copy.count # => 5sprout.count # => 2sprout.with.equal?(sprout) # => falsesprout.with == sprout # => truesprout.with('count' => 7).count # => 7
begin sprout.with({count: 1})rescue ArgumentError => e e.message # => "Seedling#with takes keyword arguments only, got 1 positional; pass a Hash as with(**hash)"endEquality and hashing
Section titled “Equality and hashing”== and eql? hold when the other object is an instance of exactly the same class with equal attributes. A subclass instance never equals its parent’s, in either direction, and errors and validity are ignored. hash is built from the class and the attributes, so equal instances collapse in a Set and work as Hash keys.
class Potted < Seedling; end
Seedling.new(species: 'Fern', count: 2) == Seedling.new(species: 'Fern', count: '2') # => trueSeedling.new(species: 'Fern') == Potted.new(species: 'Fern') # => falsePotted.new(species: 'Fern') == Seedling.new(species: 'Fern') # => false{Seedling.new(species: 'Fern') => :found}[Seedling.new(species: 'Fern')] # => :founddup and clone
Section titled “dup and clone”Both produce a shallow copy, so nested structs and arrays are shared with the original. The copy owns an Errors object seeded with copies of the original’s messages, which means editing a field on the copy never alters the original’s valid?. dup of a frozen instance comes back unfrozen, clone keeps it frozen, and clone(freeze: false) drops the freeze. Class-level immutability carries over.
original = Seedling.new(species: 'Fern', count: 2)copy = original.dupcopy.count = 'lots'original.valid? # => truecopy.valid? # => false
frozen = Seedling.new(species: 'Fern').freezefrozen.dup.frozen? # => falsefrozen.clone.frozen? # => truefrozen.clone(freeze: false).frozen? # => falseinspect and pp
Section titled “inspect and pp”inspect prints #<ClassName field: value, field: value> in declaration order, each value through its own inspect. An anonymous class shows as AnonymousFieldStruct, and a class without fields prints #<Name >. An instance with errors gets errors: {field: ["message"]} before the closing bracket, and a valid one gets no suffix. Sensitive non-nil values print as [FILTERED] while nil still shows. pp applies the same masking, nested structs and arrays of them included. inspect reads the errors as they are and never validates again.
Seedling.new(species: 'Fern', count: 2).inspect # => '#<Seedling species: "Fern", count: 2>'Seedling.new.inspect # => '#<Seedling species: nil, count: 1 errors: {species: ["is required"]}>'Class.new(FieldStruct::Base).new.inspect # => '#<AnonymousFieldStruct >'Pattern matching
Section titled “Pattern matching”deconstruct_keys(keys) gives every attribute for nil and attributes.slice(*keys) otherwise, so undeclared keys are absent. deconstruct gives the values in declaration order. Nested structs recurse since they speak the same protocol, and find patterns over arrays of structs work. Names mapped by serialize, descriptions and errors take no part.
sprout = Seedling.new(species: 'Fern', count: 2)sprout.deconstruct_keys(nil) # => {species: "Fern", count: 2}sprout.deconstruct_keys([:species, :colour]) # => {species: "Fern"}sprout.deconstruct # => ["Fern", 2]
result = case sprout in {species: String => name, count: Integer => n} then [name, n] endresult # => ["Fern", 2]model_name and to_model
Section titled “model_name and to_model”Klass.model_name, which instances also answer, returns a FieldStruct::ModelName, memoized per class. Form builders and other code that expects an ActiveModel-shaped object can read a name from it. to_model returns self.
| Reader | Value for Seedling |
|---|---|
name |
"Seedling", the full class name |
element, singular |
"seedling", the snake_case of the last :: segment |
param_key |
"seedling", the same as singular |
plural |
"seedlings", only element plus s |
to_s, to_str |
the same as name |
The plural is naive by design: Cactus becomes "cactuss" and Tomato becomes "tomatos". FieldStruct does not inflect.
param_key is what Rails’ form_with model: nests the fields under, so a form for a seedling sends seedling[species]. ActiveModel would use the whole path (nursery_seedling for Nursery::Seedling); a struct keeps the last segment, and form_with scope: picks another key when two classes end the same way. A struct has no routes or persisted?, so always pass url::
<%= form_with model: @seedling, url: '/seedlings' do |f| %> <%= f.text_field :species %><% end %>Seedling.model_name.name # => "Seedling"Seedling.model_name.singular # => "seedling"Seedling.model_name.plural # => "seedlings"Seedling.model_name.param_key # => "seedling"Seedling.new(species: 'Fern').model_name.element # => "seedling"Seedling.new(species: 'Fern').to_model.class # => SeedlingSee also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.