=pod

=for vim
   vim: tw=72 ts=3 sts=3 sw=3 et ai :

=encoding utf8

=head1 NAME

Data::Resolver::RoleComplain - role for raising exceptions


=head1 SYNOPSIS

In your class:

   package My::New::Class;
   use Moo;
   does 'Data::Resolver::RoleComplain';
   ...
   1;

Then, in your object:

   my $obj = My::New::Class->new;
   $obj->complain(404, 'Not found: this and that');
   $obj->not_found('this and that');
   say 'using Ouch!' if $obj->use_ouch; # not using ouch here

   my $obj2 = My::New::Class->new(ouch => 1);
   say 'using Ouch!' if $obj2->use_ouch; # this times it is printed

=head1 DESCRIPTION

This is a role that can be composed to gain methods useful for throwing
exceptions in a unified and consisent manner across all resolver types.

=head1 INTERFACE

This package contains a role that is supposed to be composed from a proper
class, like this:

   package My::New::Class;
   use Moo;
   does 'Data::Resolver::RoleComplain';
   ...


=head2 METHODS

The following method are available from the role:

=head3 B<< complain >>

   $obj->complain($code, $message, $data = undef);

Raise an exception with a code, a message, and some optional data.

If L</use_ouch> is true, uses L<Ouch> with the provided data. Otherwise, it
will call L<Carp/croak> with a string including the code and the message.

Compound from L<Data::Resolver::RoleComplain>.

=head3 B<< not_found >>

   $obj->not_found($key);

shortcut to raise a L</complain>t with code C<404> and a message stating
that the specific C<$key> cannot be found.

Compound from L<Data::Resolver::RoleComplain>.

=head3 B<< use_ouch >>

   my $uses_ouch = $obj->use_ouch;

boolean value indicating whether L<Ouch> is used or not.

Compound from L<Data::Resolver::RoleComplain>.


=head1 AUTHOR

Flavio Poletti <flavio@polettix.it>

=head1 COPYRIGHT AND LICENSE

Copyright 2023 by Flavio Poletti <flavio@polettix.it>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


=cut
