Stannum

A library for defining and validating data structures.

Class: Stannum::Errors

Parent Namespace
Stannum
Included Modules
Enumerable
Defined In
lib/stannum/errors.rb

Table Of Contents

Overview

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.

Examples

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] }
#   ]

Back To Top

Constructor

#initialize => Errors

Returns

Back To Top

Instance Methods

#==(other) => true, false

Also known as: eql?

Checks if the other errors object contains the same errors.

Returns

#[](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.

Examples

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: [] }]

Parameters

Returns

Raises

See Also

#[]=(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.

Examples

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] }
#   ]

Parameters

Returns

Raises

See Also

#add(type, message: nil, **data) => Stannum::Errors

Adds an error of the specified type.

Examples

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)

Parameters

Returns

Raises

#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.

Examples

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: [] }]

Overloads

#dig(keys) => Object
Parameters
  • keys (Array<Integer, String, Symbol>) — The path to the nested errors object, as an array of Integers, Strings, and Symbols.
#dig(*keys) => Object
Parameters
  • keys (Array<Integer, String, Symbol>) — The path to the nested errors object, as individual Integers, Strings, and Symbols.

Returns

Raises

See Also

#dup => Stannum::Errors

Creates a deep copy of the errors object.

Returns

#each => Enumerator
#each => Object

Overloads

#each => Enumerator

Returns an Enumerator that iterates through the errors.

Returns
  • (Enumerator)
#each => Object

Iterates through the errors, yielding each error to the provided block.

Yield Parameters
  • error (Hash{Symbol => Object}) — The error object. Each error is a hash containing the keys :data, :message, :path and :type.

#empty? => true, false

Also known as: blank?

Checks if the errors object contains any errors.

Returns

#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.

Overloads

#group_by_path => Object
#group_by_path(&block) => Object

Groups the values returned by the block by the error path.

Yield Parameters
  • error (Hash<Symbol>) — the error Hash.

Returns

#inspect => String

Returns

#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.

Parameters

Returns

Raises

See Also

#size => Integer

Also known as: count

The number of errors in the errors object.

Returns

#summary => String

Generates a text summary of the errors.

Returns

#to_a => Array<Hash>

Generates an array of error objects.

Each error is a hash containing the keys :data, :message, :path and :type.

Returns

#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.

Parameters

Returns

Raises

See Also

#with_messages(force: false, strategy: nil) => Stannum::Errors

Creates a copy of the errors and generates error messages for each error.

Parameters

Returns

Back To Top


Back to Documentation | Versions | 0.4 | Reference | Stannum