A library for defining and validating data structures.
An errors object represents a collection of errors.
Most of the time, an end user will not be creating an Errors object directly. Instead, an errors object may be returned by a process that validates or coerces data to an expected form. For one such example, see the Stannum::Constraint and its subclasses.
Internally, an errors object is an Array of errors. Each error is represented by a Hash containing the keys :data, :message, :path and :type.
Creating An Errors Object
errors = Stannum::Errors.new
Adding Errors
errors.add(:not_numeric)
# Add an error with a custom message.
errors.add(:invalid, message: 'is not valid')
# Add an error with additional data.
errors.add(:out_of_range, min: 0, max: 10)
# Add multiple errors.
errors.add(:first_error).add(:second_error).add(:third_error)
Viewing The Errors
errors.empty? #=> false
errors.size #=> 6
errors.each { |err| } #=> yields each error to the block
errors.to_a #=> returns an array containing each error
Accessing Nested Errors via a Key
errors = Stannum::Errors.new
child = errors[:spell]
child.size #=> 0
child.to_a #=> []
child.add(:insufficient_mana)
child.size # 1
child.to_a # [{ type: :insufficient_mana, path: [] }]
# Adding an error to a child makes it available on a parent.
errors.size # 1
errors.to_a # [{ type: :insufficient_mana, path: [:spell] }]
Accessing Nested Errors via an Index
errors = Stannum::Errors.new
child = errors[1]
child.size #=> 0
child.to_a #=> []
child.add(:unknown_monster)
child.size # 1
child.to_a # [{ type: :unknown_monster, path: [] }]
# Adding an error to a child makes it available on a parent.
errors.size # 1
errors.to_a # [{ type: :unknown_monster, path: [1] }]
Accessing Deeply Nested Errors
errors = Stannum::Errors.new
errors[:towns][1][:name].add(:unpronounceable)
errors.size #=> 1
errors.to_a #=> [{ type: :unpronounceable, path: [:towns, 1, :name] }]
errors[:towns].size #=> 1
errors[:towns].to_a #=> [{ type: :unpronounceable, path: [1, :name] }]
errors[:towns][1].size #=> 1
errors[:towns][1].to_a #=> [{ type: :unpronounceable, path: [:name] }]
errors[:towns][1][:name].size #=> 1
errors[:towns][1][:name].to_a #=> [{ type: :unpronounceable, path: [] }]
# Can also access nested properties via #dig.
errors.dig(:towns, 1, :name).to_a #=> [{ type: :unpronounceable, path: [] }]
Replacing Errors
errors = Cuprum::Errors.new
errors[:potions][:ingredients].add(:missing_rabbits_foot)
errors.size #=> 1
other = Cuprum::Errors.new.add(:too_hot, :brew_longer, :foul_smelling)
errors[:potions] = other
errors.size #=> 3
errors.to_a
#=> [
# { type: :brew_longer, path: [:potions] },
# { type: :foul_smelling, path: [:potions] },
# { type: :too_hot, path: [:potions] }
# ]
Replacing Nested Errors
errors = Cuprum::Errors.new
errors[:armory].add(:empty)
other = Cuprum::Errors.new
other.dig(:weapons, 0).add(:needs_sharpening)
other.dig(:weapons, 1).add(:rusty).add(:out_of_ammo)
errors[:armory] = other
errors.size #=> 3
errors.to_a
#=> [
# { type: needs_sharpening, path: [:armory, :weapons, 0] },
# { type: out_of_ammo, path: [:armory, :weapons, 1] },
# { type: rusty, path: [:armory, :weapons, 1] }
# ]
#initialize => Errors
#==(other) => true, false
Also known as:
eql?
Checks if the other errors object contains the same errors.
#[](key) => Stannum::Errors
Accesses a nested errors object.
Each errors object can have one or more children, each of which is itself an errors object. These nested errors represent errors on some subset of the main object - for example, a failed validation of a named property, of the value in a key-value pair, or of an indexed value in an ordered collection.
The children are created as needed and are stored with either an integer or a symbol key. Calling errors[1] multiple times will always return the same errors object. Likewise, calling errors[:some_key] multiple times will return the same object, and calling errors[‘some_key’] will return that same errors object as well.
Accessing Nested Errors via a Key
errors = Stannum::Errors.new
child = errors[:spell]
child.size #=> 0
child.to_a #=> []
child.add(:insufficient_mana)
child.size # 1
child.to_a # [{ type: :insufficient_mana, path: [] }]
# Adding an error to a child makes it available on a parent.
errors.size # 1
errors.to_a # [{ type: :insufficient_mana, path: [:spell] }]
Accessing Nested Errors via an Index
errors = Stannum::Errors.new
child = errors[1]
child.size #=> 0
child.to_a #=> []
child.add(:unknown_monster)
child.size # 1
child.to_a # [{ type: :unknown_monster, path: [] }]
# Adding an error to a child makes it available on a parent.
errors.size # 1
errors.to_a # [{ type: :unknown_monster, path: [1] }]
Accessing Deeply Nested Errors
errors = Stannum::Errors.new
errors[:towns][1][:name].add(:unpronounceable)
errors.size #=> 1
errors.to_a #=> [{ type: :unpronounceable, path: [:towns, 1, :name] }]
errors[:towns].size #=> 1
errors[:towns].to_a #=> [{ type: :unpronounceable, path: [1, :name] }]
errors[:towns][1].size #=> 1
errors[:towns][1].to_a #=> [{ type: :unpronounceable, path: [:name] }]
errors[:towns][1][:name].size #=> 1
errors[:towns][1][:name].to_a #=> [{ type: :unpronounceable, path: [] }]
#[]=(key, value) => Object
Replaces the child errors with the specified errors object or Array.
If the given value is nil or an empty array, the #[]= operator will remove the child errors object at the given key, removing all errors within that namespace and all namespaces nested inside it.
If the given value is an errors object or an Array of errors object, the #[]= operation will replace the child errors object at the given key, removing all existing errors and adding the new errors. Each added error will use its nested path (if any) as a relative path from the given key.
Replacing Errors
errors = Cuprum::Errors.new
errors[:potions][:ingredients].add(:missing_rabbits_foot)
errors.size #=> 1
other = Cuprum::Errors.new.add(:too_hot, :brew_longer, :foul_smelling)
errors[:potions] = other
errors.size #=> 3
errors.to_a
#=> [
# { type: :brew_longer, path: [:potions] },
# { type: :foul_smelling, path: [:potions] },
# { type: :too_hot, path: [:potions] }
# ]
Replacing Nested Errors
errors = Cuprum::Errors.new
errors[:armory].add(:empty)
other = Cuprum::Errors.new
other.dig(:weapons, 0).add(:needs_sharpening)
other.dig(:weapons, 1).add(:rusty).add(:out_of_ammo)
errors[:armory] = other
errors.size #=> 3
errors.to_a
#=> [
# { type: needs_sharpening, path: [:armory, :weapons, 0] },
# { type: out_of_ammo, path: [:armory, :weapons, 1] },
# { type: rusty, path: [:armory, :weapons, 1] }
# ]
#add(type, message: nil, **data) => Stannum::Errors
Adds an error of the specified type.
Adding An Error
errors = Stannum::Errors.new.add(:not_found)
Adding An Error With A Message
errors = Stannum::Errors.new.add(:not_found, message: 'is missing')
Adding Multiple Errors
errors = Stannum::Errors.new
errors
.add(:not_numeric)
.add(:not_integer, message: 'is outside the range')
.add(:not_in_range)
#dig(keys) => Object
#dig(*keys) => Object
Accesses a (possibly deeply) nested errors object.
Similiar to the #[] method, but can access a deeply nested errors object as well. The #dig method can take either a list of one or more keys (Integers, Strings, and Symbols) as arguments, or an Array of keys. Calling errors.dig is equivalent to calling errors[] with each key in sequence.
Accessing Nested Errors via a Key
errors = Stannum::Errors.new
child = errors.dig(:spell)
child.size #=> 0
child.to_a #=> []
child.add(:insufficient_mana)
child.size # 1
child.to_a # [{ type: :insufficient_mana, path: [] }]
# Adding an error to a child makes it available on a parent.
errors.size # 1
errors.to_a # [{ type: :insufficient_mana, path: [:spell] }]
Accessing Nested Errors via an Index
errors = Stannum::Errors.new
child = errors.dig(1)
child.size #=> 0
child.to_a #=> []
child.add(:unknown_monster)
child.size # 1
child.to_a # [{ type: :unknown_monster, path: [] }]
# Adding an error to a child makes it available on a parent.
errors.size # 1
errors.to_a # [{ type: :unknown_monster, path: [1] }]
Accessing Deeply Nested Errors
errors = Stannum::Errors.new
errors.dig(:towns, 1, :name).add(:unpronounceable)
errors.size #=> 1
errors.to_a #=> [{ type: :unpronounceable, path: [:towns, 1, :name] }]
errors.dig(:towns).size #=> 1
errors.dig(:towns).to_a #=> [{ type: :unpronounceable, path: [1, :name] }]
errors.dig(:towns, 1).size #=> 1
errors.dig(:towns, 1).to_a #=> [{ type: :unpronounceable, path: [:name] }]
errors.dig(:towns, 1, :name).size #=> 1
errors.dig(:towns, 1, :name).to_a #=> [{ type: :unpronounceable, path: [] }]
#dig(keys) => Object
#dig(*keys) => Object
#dup => Stannum::Errors
Creates a deep copy of the errors object.
#each => Enumerator
#each => Object
#each => Enumerator
Returns an Enumerator that iterates through the errors.
#each => Object
Iterates through the errors, yielding each error to the provided block.
#empty? => true, false
Also known as:
blank?
Checks if the errors object contains any errors.
#group_by_path => Object
#group_by_path(&block) => Object
Groups the errors by the error path.
Generates a Hash whose keys are the unique error :path values. For each path, the corresponding value is the Array of all errors with that path.
This will flatten paths: an error with path [:parts] will be grouped in a separate array from a part with path [:parts, :assemblies].
Errors with an empty path will be grouped with a key of an empty Array.
#group_by_path => Object
#group_by_path(&block) => Object
Groups the values returned by the block by the error path.
#inspect => String
#merge(value) => Stannum::Errors
Adds the given errors to a copy of the errors object.
Creates a copy of the errors object, and then adds each error in the passed in errors object or array to the copy. The copy will thus contain all of the errors from the original object and all of the errors from the passed in object. The original object is not changed.
#size => Integer
Also known as:
count
The number of errors in the errors object.
#summary => String
Generates a text summary of the errors.
#to_a => Array<Hash>
Generates an array of error objects.
Each error is a hash containing the keys :data, :message, :path and :type.
#update(value) => self
Adds the given errors to the errors object.
Adds each error in the passed in errors object or array to the current errors object. It will then contain all of the original errors and all of the errors from the passed in object. This changes the current object.
#with_messages(force: false, strategy: nil) => Stannum::Errors
Creates a copy of the errors and generates error messages for each error.
Back to Documentation | Versions | 0.4 | Reference | Stannum