NAME

Valiant::Errors - A collection of errors associated with an object

SYNOPSIS

DESCRIPTION

A collection of errors (each instances of Valiant::Error) associated with attributes or a model. This class provides methods for adding, retrieving and introspecting error, typically via a Valiant::Validator or Valiant::Validator::Each subclass.

The goal of this class is to make it as easy as possible to work with and understand errors that have been added to your instance. In general you will never make an instance of this directly since it will be used via the Valiant::Validates role.

ATTRIBUTES

This class defined the following attributes

object

This is a weak reference to the object which the errors belong to.

errors

This is an instance of Data::Perl::Collection::Array which in a collection of Valiant::Error objects added by validators.

i18n

The internationalization and translation class. Generally this is an instance of Valiant::I18N. You won't need to supply this as it normally is built automatically.

METHODS

The class defines the following methods

count

size

The number of errors collected. If there are no errors then the size is 0.

empty

blank

Returns true if there are no errors collected.

any(\&code)

Accepts a coderef that will receive each error object in the collect and return true if any of the coderef calls return true. Used to determine if the errors collection contains at least one type of error.

    my $has_invalids = $user1->errors->any(sub {
      ${\$_->type} eq 'invalid';
    });

copy

Copy an errors collection into the current (replacing any existing). The copies are new instances of Valiant::Error, not references to the original objects.

import_error ($error)

Given a single Valiant::Error inport it into the current errors collection

merge ($collectio)

Given a Valiant::Errors collection, merge it into the current one.

where ($attribute, $message, \%options)

return all the Valiant::Error objects in the current collection which match criteria.

include ($attribute)

Returns +true+ if the error messages include an error for the given key +attribute+, +false+ otherwise.

delete ($attribute)

Delete messages for +key+. Returns the deleted messages.

each ($coderef)

Iterates through each error key, value pair in the error messages hash. Yields the attribute and the error for that attribute. If the attribute has more than one error message, yields once for each error message.

    $object->errors->each*(sub {
      my ($attribute, $message) = @_;
    });

If the error is a model error then $attribute will be '*'.

model_messages

Returns an array of all the errors that are associated with the model (Localized if needed).

attribute_messages

Returns an array of all the errors that are associated with attributes (localized if needed).

full_attribute_messages

Returns an array of the full messages of all attributes (localized if needed).

to_hash (?$flag)

Returns a hash where each key is an attribute (or '*' for the model) and each value is an arrayref of errors. ?$flag when true will return the full messages for each error.

add ($attribute|undef, $message, \%opts)

Add a new error message to the object. Error can be associated with an attribute or with the object itself. $message can be one of:

A string

If a string this is the error message recorded.

    validates name => (
      format => 'alphabetic',
      length => [3,20],
      message => 'Unacceptable Name',
    );

A translation tag

    use Valiant::I18N;

    validates name => (
      format => 'alphabetic',
      length => [3,20],
      message => _t('bad_name'),
    );

This will look up a translated version of the tag. See Valiant::I18N for more details.

A scalar reference

    validates name => (
      format => 'alphabetic',
      length => [3,20],
      message => \'Unacceptable {{attribute}}',
    );

Similar to string but we will expand any placeholder variables which are indicated by the '{{' and '}}' tokens (which are removed from the final string). You can use any placeholder that is a key in the options hash (and you can pass additional values when you add an error). By default the following placeholder expansions are available attribute (the attribute name), value (the current attribute value), model (the human name of the model containing the attribute and object (the actual object instance that has the error).

A subroutine reference

    validates name => (
      format => 'alphabetic',
      length => [3,20],
      message => sub {
        my ($self, $attr, $value, $opts) = @_;
        return "Unacceptable $attr!";
      }
    );

Similar to the scalar reference option just more flexible since you can write custom code to build the error message. For example you could return different error messages based on the identity of a person. Also if you return a translation tag instead of a simple string we will attempt to resolve it to a translated string (see Valiant::I18N).

added ($attribute|undef, $message, \%opts)

Return true if the error has already been created.

of_kind ($attribute|undef, $message)

Similar to <added> expect we don't need to match options

messages

An array of the error messages. All translation tags will be translated to strings in the expected local langauge.

full_messages

An array of the full messages (localized if needed).

messages_for ($attribute)

An array of all the messages for the given attribute (localized if needed).

full_messages_for ($attribute)

An array of all the full messages for the given attribute (localized if needed).

JSONification

This class provides a TO_JSON method suitable for use in some of the common JSON serializers. When supported it will delegate the job of turning the object into a hash that can be serialized to JSON to the to_hash method.

AUTHOR

See Valiant

COPYRIGHT & LICENSE