File Coverage

lib/Class/Usul/Exception.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Class::Usul::Exception;
2              
3 29     29   4492 use namespace::autoclean;
  29         103405  
  29         217  
4              
5 29     29   12661 use Unexpected::Functions qw( has_exception );
  29         82426  
  29         181  
6 29     29   20319 use Unexpected::Types qw( Int Str );
  29         2256556  
  29         379  
7 29     29   41046 use Moo;
  29         139166  
  29         150  
8              
9             extends q(Unexpected);
10             with q(Unexpected::TraitFor::ErrorLeader);
11             with q(Unexpected::TraitFor::ExceptionClasses);
12              
13             my $class = __PACKAGE__;
14              
15             $class->ignore_class( 'Class::Usul::IPC', 'Sub::Quote' );
16              
17             has_exception $class;
18              
19             has_exception 'DateTimeCoercion' => parents => [ $class ],
20             error => 'String [_1] will not coerce to a Unix time value';
21              
22             has_exception 'Tainted' => parents => [ $class ],
23             error => 'String [_1] contains possible taint';
24              
25             has_exception 'TimeOut' => parents => [ $class ],
26             error => 'Command [_1] timed out after [_2] seconds';
27              
28             has '+class' => default => $class;
29              
30             has 'out' => is => 'ro', isa => Str, default => q();
31              
32             has 'rv' => is => 'ro', isa => Int, default => 1;
33              
34             has 'time' => is => 'ro', isa => Int, default => CORE::time(),
35             init_arg => undef;
36              
37             1;
38              
39             __END__
40              
41             =pod
42              
43             =encoding utf8
44              
45             =head1 Name
46              
47             Class::Usul::Exception - Exception handling
48              
49             =head1 Synopsis
50              
51             use Class::Usul::Functions qw(throw);
52             use Try::Tiny;
53              
54             sub some_method {
55             my $self = shift;
56              
57             try { this_will_fail }
58             catch { throw $_ };
59             }
60              
61             # OR
62             use Class::Usul::Exception;
63              
64             sub some_method {
65             my $self = shift;
66              
67             eval { this_will_fail };
68             Class::Usul::Exception->throw_on_error;
69             }
70              
71             # THEN
72             try { $self->some_method() }
73             catch { warn $_."\n\n".$_->stacktrace."\n" };
74              
75             =head1 Description
76              
77             An exception class that supports error messages with placeholders, a
78             L</throw> method with automatic re-throw upon detection of self,
79             conditional throw if an exception was caught and a simplified
80             stacktrace
81              
82             Error objects are overloaded to stringify to the full error message plus a
83             leader
84              
85             =head1 Configuration and Environment
86              
87             The C<< __PACKAGE__->ignore_class >> class method contains a classes
88             whose presence should be ignored by the error message leader
89              
90             Defines the following list of read only attributes;
91              
92             =over 3
93              
94             =item C<args>
95              
96             An array ref of parameters substituted in for the placeholders in the
97             error message when the error is localised
98              
99             =item C<class>
100              
101             Defaults to C<__PACKAGE__>. Can be used to differentiate different classes of
102             error
103              
104             =item C<error>
105              
106             The actually error message which defaults to C<Unknown error>. Can contain
107             placeholders of the form C<< [_<n>] >> where C<< <n> >> is an integer
108             starting at one
109              
110             =item C<leader>
111              
112             Set to the package and line number where the error should be reported
113              
114             =item C<level>
115              
116             A positive integer which defaults to one. How many additional stack frames
117             to pop before calculating the C<leader> attribute
118              
119             =item C<out>
120              
121             Defaults to null. May contain the output from whatever just threw the
122             exception
123              
124             =item C<rv>
125              
126             Return value which defaults to one
127              
128             =item C<time>
129              
130             A positive integer which defaults to the C<CORE::time> the exception was
131             thrown
132              
133             =back
134              
135             =head1 Subroutines/Methods
136              
137             =head2 C<BUILDARGS>
138              
139             Doesn't modify the C<BUILDARGS> method. This is here to workaround a
140             bug in L<Moo> and / or L<Test::Pod::Coverage>
141              
142             =head2 C<as_string>
143              
144             $error_text = $self->as_string;
145              
146             This is what the object stringifies to, including the C<leader> attribute
147              
148             =head2 C<caught>
149              
150             $self = $class->caught( [ @args ] );
151              
152             Catches and returns a thrown exception or generates a new exception if
153             C<$EVAL_ERROR> has been set. Returns either an exception object or undef
154              
155             =head2 C<clone>
156              
157             $cloned_exception_object_ref = $self->clone( $args );
158              
159             Returns a clone of the invocant. The optional C<$args> hash reference mutates
160             the returned clone
161              
162             =head2 C<stacktrace>
163              
164             $lines = $self->stacktrace( $num_lines_to_skip );
165              
166             Return the stack trace. Defaults to skipping zero lines of output
167              
168             =head2 C<throw>
169              
170             $class->throw 'Path [_1] not found', [ 'pathname' ];
171              
172             Create (or re-throw) an exception. If the passed parameter is a
173             blessed reference it is re-thrown. If a single scalar is passed it is
174             taken to be an error message, a new exception is created with all
175             other parameters taking their default values. If more than one
176             parameter is passed the it is treated as a list and used to
177             instantiate the new exception. The 'error' parameter must be provided
178             in this case
179              
180             =head2 C<throw_on_error>
181              
182             $class->throw_on_error( [ @args ] );
183              
184             Calls L</caught> passing in the options C<@args> and if there was an
185             exception L</throw>s it
186              
187             =head1 Diagnostics
188              
189             None
190              
191             =head1 Dependencies
192              
193             =over 3
194              
195             =item L<Moo>
196              
197             =item L<Unexpected>
198              
199             =back
200              
201             =head1 Incompatibilities
202              
203             There are no known incompatibilities in this module
204              
205             =head1 Bugs and Limitations
206              
207             There are no known bugs in this module.
208             Please report problems to the address below.
209             Patches are welcome
210              
211             =head1 Author
212              
213             Peter Flanigan C<< <pjfl@cpan.org> >>
214              
215             =head1 License and Copyright
216              
217             Copyright (c) 2017 Peter Flanigan. All rights reserved
218              
219             This program is free software; you can redistribute it and/or modify it
220             under the same terms as Perl itself. See L<perlartistic>
221              
222             This program is distributed in the hope that it will be useful,
223             but WITHOUT WARRANTY; without even the implied warranty of
224             MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
225              
226             =cut
227              
228             # Local Variables:
229             # mode: perl
230             # tab-width: 3
231             # End: