diff options
Diffstat (limited to 'lib/Moose/Manual/Exceptions.pod')
| -rw-r--r-- | lib/Moose/Manual/Exceptions.pod | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/lib/Moose/Manual/Exceptions.pod b/lib/Moose/Manual/Exceptions.pod new file mode 100644 index 0000000..61435a2 --- /dev/null +++ b/lib/Moose/Manual/Exceptions.pod @@ -0,0 +1,239 @@ +# PODNAME: Moose::Manual::Exceptions +# ABSTRACT: Moose's exceptions + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Manual::Exceptions - Moose's exceptions + +=head1 VERSION + +version 2.1405 + +=head1 EXCEPTIONS IN MOOSE + +Moose will throw an exception for all error conditions. This applies both to +code in the Moose core I<as well> as to all code generated when a class is +made immutable. All exceptions are subclasses of the C<Moose::Exception> +class. + +Each type of error has its own unique subclass, and many subclasses have +additional attributes to provide more information about the error's context, +such as what classes or roles were involved. + +=head1 EXCEPTION STRINGIFICATION + +By default, Moose exceptions remove Moose internals from the stack trace. If +you set the C<MOOSE_FULL_EXCEPTION> environment variable to a true value, then +the Moose internals will be included in the trace. + +=head1 HANDLING MOOSE EXCEPTIONS + +Because Moose's exceptions use the standard C<die> mechanism, you are free to +catch and handle errors however you like. You could use an C<eval> block to +catch Moose exceptions. However, the Moose team strongly recommends using +L<Try::Tiny> instead. Please refer to L<Try::Tiny>'s documentation for a +discussion of how C<eval> is dangerous. + +The following example demonstrates how to catch and inspect a +L<Moose::Exception>. For the sake of simplicity, we will cause a very simple +error. The C<extends> keywords expects a list of superclass names. If we pass +no superclass names, Moose will throw an instance of +L<Moose::Exception::ExtendsMissingArgs>. + +=head2 Catching with Try::Tiny + + use warnings; + use strict; + use Try::Tiny; + + try { + package Example::Exception; + use Moose; + extends; # <-- error! + } + catch { + # $_ contains the instance of the exception thrown by the above try + # block, but $_ may get clobbered, so we should copy its value to + # another variable. + my $e = $_; + + # Exception objects are not ubiquitous in Perl, so we must check + # whether $e is blessed. We also need to ensure that $e is actually + # the kind of exception we were expecting. + if ( blessed $e + && $e->isa('Moose::Exception::ExtendsMissingArgs') ) { + + my $class_name = $e->class_name; + warn "You forgot to specify a superclass for $class_name, silly!"; + } + + # It's either another type of an object or not an object at all. + else { + warn "$e\n"; + } + } + +=head2 Example of catching ValidationFailedForTypeConstraint + + use warnings; + use strict; + + use Try::Tiny; + + { + package Person; + use Moose; + use Moose::Util::TypeConstraints; + + subtype 'NameStr', + as 'Str', + where { $_ =~ /^[a-zA-Z]+$/; }; + + has age => ( + is => 'ro', + isa => 'Int', + required => 1 + ); + + has name => ( + is => 'ro', + isa => 'NameStr', + required => 1 + ); + } + + my $person; + while ( !$person ) { + try { + print 'Enter your age : '; + my $age = <STDIN>; + chomp $age; + print 'Enter your name : '; + my $name = <STDIN>; + chomp $name; + $person = Person->new( + age => $age, + name => $name + ); + my $person_name = $person->name; + my $person_age = $person->age; + print "$person_name is $person_age years old\n"; + } + catch { + my $e = $_; + + if ( + blessed $e + && $e->isa( + 'Moose::Exception::ValidationFailedForTypeConstraint') + ) { + + my $attribute_name = $e->attribute->name; + my $type_name = $e->type->name; + my $value = $e->value; + + warn + "You entered $value for $attribute_name, which is not a $type_name!"; + } + else { + warn "$e\n"; + } + } + } + +=head2 Example of catching AttributeIsRequired + + use warnings; + use strict; + use Try::Tiny; + + { + package Example::RequiredAttribute; + use Moose; + + has required_attribute => ( + is => 'ro', + isa => 'Int', + required => 1 + ); + } + + try { + # we're not passing required_attribute, so it'll throw an exception + my $object = Example::RequiredAttribute->new(); + } + catch { + my $e = $_; + if ( blessed $e && $e->isa('Moose::Exception::AttributeIsRequired') ) + { + warn $e->message, "\n"; + } + else { + warn "$e\n"; + } + }; + +=head1 MOOSE EXCEPTION CLASSES + +All the exception classes are listed in L<Moose::Manual::Exceptions::Manifest>. + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little <stevan.little@iinteractive.com> + +=item * + +Dave Rolsky <autarch@urth.org> + +=item * + +Jesse Luehrs <doy@tozt.net> + +=item * + +Shawn M Moore <code@sartak.org> + +=item * + +יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org> + +=item * + +Karen Etheridge <ether@cpan.org> + +=item * + +Florian Ragwitz <rafl@debian.org> + +=item * + +Hans Dieter Pearcey <hdp@weftsoar.net> + +=item * + +Chris Prather <chris@prather.org> + +=item * + +Matt S Trout <mst@shadowcat.co.uk> + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc.. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut |