abstract struct Change::Changeset(T, U)

Overview

T is the type of the stored instance, inferrable from initialize. U is a union of the type of all managed fields on that instance. U does not need to (and generally should not) include Nil in the union, it will automatically be added where needed.

Defined in:

change/changeset.cr
change/changeset/errors.cr
change/changeset/validations.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(instance : T) #

Create a new changeset using #instance as the base for defining changes.


[View source]

Instance Method Detail

def add_error(field : String, message : String) : self #

Add an error to this changeset. field is the field that the error applies to, and message is a description about the error. Errors will be coerced into a ChangesetError object.

Calling this method also implicitly marks this Changeset as invalid.


[View source]
abstract def apply_changes(inst : T) : T #

Like apply_changes/0, but instead applying the changes to the given instance.


[View source]
abstract def apply_changes : T #

Assign each changed value from this changeset onto the instance owned by this Changeset (in the #instance property). Returns the updated instance directly.

This is considered a safe operation, as only validated changes are stored in the changeset.


[View source]
def cast(props, permitted : Array) : self #

For each field in permitted, attempt to cast the value from props into the type of the corresponding field on the model.

If any field cannot be casted successfully, the changeset is marked as invalid, but all remaining casts will still be attempted.

nil is always permitted in casts.


[View source]
abstract def changed? : Bool #

Returns true if any field in this changeset has been marked as changed.


[View source]
abstract def changes_hash : Hash(String, String | Nil) #

Returns a hash of changes currently stored in this changeset, including fields that have been changed to nil. Fields without changes are not included in this hash, meaning a changeset with no changes will return an empty hash.


[View source]
abstract def each_change(&block : String, U | Nil -> _) #

Calls the given block once for every accepted change currently in the changeset. The block is passed the name of the changed field and its accepted value as arguments. Fields that have not been changed will not be yielded to the block.

If the changeset has no accepted changes, the block will not be called.


[View source]
abstract def each_field(&block : String, U | Nil -> _) #

Calls the given block once for every field in the changeset, including fields that have not been changed. Fields with accepted changes will yield the changed value, while fields without changes will yield the value from the stored instance.

The block will always be called for every field managed by the changeset.


[View source]
def errors : Array(ChangesetError) #

[View source]
def errors=(errors : Array(ChangesetError)) #

[View source]
abstract def get_change(field : String, default = nil) : U | Nil #

Return the stored change for the given field from this changeset, or default if the field has not been changed.

Even if the value of the change is nil, as long as the field has been marked as changed, that value will be returned instead of default.


[View source]
abstract def get_field(field : String, default = nil) : U | Nil #

Similar to #get_change but if no change is present, this method first checks the stored instance for a defined value, and only returns default if the instance's existing value is nil.


[View source]
abstract def has_field?(field : String) : Bool #

Returns true if field is a valid field name in this changeset.


[View source]
def instance : T #

[View source]
def instance=(instance : T) #

[View source]
def valid=(valid : Bool) #

[View source]
def valid? : Bool #

[View source]
def validate_required(field : String | Symbol) : self #

Validates that the given field is present in this Changeset, either as a change, or as an existing value on the stored instance. Presence is defined as anything other than a value of nil.

If the field is not present, an error is added and the changeset is marked as invalid.

If the field is not a valid field for this changeset, it is ignored.


[View source]
def validate_required(fields : Array(String) | Array(Symbol)) : self #

Validate the multiple fields are present in the Changeset. See #validate_required(String) for more information.


[View source]