| 1 |
#============================================================= -*-Perl-*- |
| 2 |
# |
| 3 |
# Template::Exception |
| 4 |
# |
| 5 |
# DESCRIPTION |
| 6 |
# Module implementing a generic exception class used for error handling |
| 7 |
# in the Template Toolkit. |
| 8 |
# |
| 9 |
# AUTHOR |
| 10 |
# Andy Wardley <[email protected]> |
| 11 |
# |
| 12 |
# COPYRIGHT |
| 13 |
# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
| 14 |
# |
| 15 |
# This module is free software; you can redistribute it and/or |
| 16 |
# modify it under the same terms as Perl itself. |
| 17 |
# |
| 18 |
#======================================================================== |
| 19 |
|
| 20 |
package Template::Exception; |
| 21 |
|
| 22 |
use strict; |
| 23 |
use warnings; |
| 24 |
use constant TYPE => 0; |
| 25 |
use constant INFO => 1; |
| 26 |
use constant TEXT => 2; |
| 27 |
use overload q|""| => "as_string", fallback => 1; |
| 28 |
|
| 29 |
our $VERSION = 2.70; |
| 30 |
|
| 31 |
|
| 32 |
#------------------------------------------------------------------------ |
| 33 |
# new($type, $info, \$text) |
| 34 |
# |
| 35 |
# Constructor method used to instantiate a new Template::Exception |
| 36 |
# object. The first parameter should contain the exception type. This |
| 37 |
# can be any arbitrary string of the caller's choice to represent a |
| 38 |
# specific exception. The second parameter should contain any |
| 39 |
# information (i.e. error message or data reference) relevant to the |
| 40 |
# specific exception event. The third optional parameter may be a |
| 41 |
# reference to a scalar containing output text from the template |
| 42 |
# block up to the point where the exception was thrown. |
| 43 |
#------------------------------------------------------------------------ |
| 44 |
|
| 45 |
sub new { |
| 46 |
my ($class, $type, $info, $textref) = @_; |
| 47 |
bless [ $type, $info, $textref ], $class; |
| 48 |
} |
| 49 |
|
| 50 |
|
| 51 |
#------------------------------------------------------------------------ |
| 52 |
# type() |
| 53 |
# info() |
| 54 |
# type_info() |
| 55 |
# |
| 56 |
# Accessor methods to return the internal TYPE and INFO fields. |
| 57 |
#------------------------------------------------------------------------ |
| 58 |
|
| 59 |
sub type { |
| 60 |
$_[0]->[ TYPE ]; |
| 61 |
} |
| 62 |
|
| 63 |
sub info { |
| 64 |
$_[0]->[ INFO ]; |
| 65 |
} |
| 66 |
|
| 67 |
sub type_info { |
| 68 |
my $self = shift; |
| 69 |
@$self[ TYPE, INFO ]; |
| 70 |
} |
| 71 |
|
| 72 |
#------------------------------------------------------------------------ |
| 73 |
# text() |
| 74 |
# text(\$pretext) |
| 75 |
# |
| 76 |
# Method to return the text referenced by the TEXT member. A text |
| 77 |
# reference may be passed as a parameter to supercede the existing |
| 78 |
# member. The existing text is added to the *end* of the new text |
| 79 |
# before being stored. This facility is provided for template blocks |
| 80 |
# to gracefully de-nest when an exception occurs and allows them to |
| 81 |
# reconstruct their output in the correct order. |
| 82 |
#------------------------------------------------------------------------ |
| 83 |
|
| 84 |
sub text { |
| 85 |
my ($self, $newtextref) = @_; |
| 86 |
my $textref = $self->[ TEXT ]; |
| 87 |
|
| 88 |
if ($newtextref) { |
| 89 |
$$newtextref .= $$textref if $textref && $textref ne $newtextref; |
| 90 |
$self->[ TEXT ] = $newtextref; |
| 91 |
return ''; |
| 92 |
} |
| 93 |
elsif ($textref) { |
| 94 |
return $$textref; |
| 95 |
} |
| 96 |
else { |
| 97 |
return ''; |
| 98 |
} |
| 99 |
} |
| 100 |
|
| 101 |
|
| 102 |
#------------------------------------------------------------------------ |
| 103 |
# as_string() |
| 104 |
# |
| 105 |
# Accessor method to return a string indicating the exception type and |
| 106 |
# information. |
| 107 |
#------------------------------------------------------------------------ |
| 108 |
|
| 109 |
sub as_string { |
| 110 |
my $self = shift; |
| 111 |
return $self->[ TYPE ] . ' error - ' . $self->[ INFO ]; |
| 112 |
} |
| 113 |
|
| 114 |
|
| 115 |
#------------------------------------------------------------------------ |
| 116 |
# select_handler(@types) |
| 117 |
# |
| 118 |
# Selects the most appropriate handler for the exception TYPE, from |
| 119 |
# the list of types passed in as parameters. The method returns the |
| 120 |
# item which is an exact match for TYPE or the closest, more |
| 121 |
# generic handler (e.g. foo being more generic than foo.bar, etc.) |
| 122 |
#------------------------------------------------------------------------ |
| 123 |
|
| 124 |
sub select_handler { |
| 125 |
my ($self, @options) = @_; |
| 126 |
my $type = $self->[ TYPE ]; |
| 127 |
my %hlut; |
| 128 |
@hlut{ @options } = (1) x @options; |
| 129 |
|
| 130 |
while ($type) { |
| 131 |
return $type if $hlut{ $type }; |
| 132 |
|
| 133 |
# strip .element from the end of the exception type to find a |
| 134 |
# more generic handler |
| 135 |
$type =~ s/\.?[^\.]*$//; |
| 136 |
} |
| 137 |
return undef; |
| 138 |
} |
| 139 |
|
| 140 |
1; |
| 141 |
|
| 142 |
__END__ |
| 143 |
|
| 144 |
=head1 NAME |
| 145 |
|
| 146 |
Template::Exception - Exception handling class module |
| 147 |
|
| 148 |
=head1 SYNOPSIS |
| 149 |
|
| 150 |
use Template::Exception; |
| 151 |
|
| 152 |
my $exception = Template::Exception->new($type, $info); |
| 153 |
$type = $exception->type; |
| 154 |
$info = $exception->info; |
| 155 |
($type, $info) = $exception->type_info; |
| 156 |
|
| 157 |
print $exception->as_string(); |
| 158 |
|
| 159 |
$handler = $exception->select_handler(\@candidates); |
| 160 |
|
| 161 |
=head1 DESCRIPTION |
| 162 |
|
| 163 |
The C<Template::Exception> module defines an object class for |
| 164 |
representing exceptions within the template processing life cycle. |
| 165 |
Exceptions can be raised by modules within the Template Toolkit, or |
| 166 |
can be generated and returned by user code bound to template |
| 167 |
variables. |
| 168 |
|
| 169 |
Exceptions can be raised in a template using the C<THROW> directive, |
| 170 |
|
| 171 |
[% THROW user.login 'no user id: please login' %] |
| 172 |
|
| 173 |
or by calling the L<throw()|Template::Context#throw()> method on the current |
| 174 |
L<Template::Context> object, |
| 175 |
|
| 176 |
$context->throw('user.passwd', 'Incorrect Password'); |
| 177 |
$context->throw('Incorrect Password'); # type 'undef' |
| 178 |
|
| 179 |
or from Perl code by calling C<die()> with a C<Template::Exception> object, |
| 180 |
|
| 181 |
die (Template::Exception->new('user.denied', 'Invalid User ID')); |
| 182 |
|
| 183 |
or by simply calling C<die()> with an error string. This is |
| 184 |
automagically caught and converted to an exception of 'C<undef>' |
| 185 |
type (that's the literal string 'C<undef>' rather than Perl's |
| 186 |
undefined value) which can then be handled in the usual way. |
| 187 |
|
| 188 |
die "I'm sorry Dave, I can't do that"; |
| 189 |
|
| 190 |
Each exception is defined by its type and a information component |
| 191 |
(e.g. error message). The type can be any identifying string and may |
| 192 |
contain dotted components (e.g. 'C<foo>', 'C<foo.bar>', 'C<foo.bar.baz>'). |
| 193 |
Exception types are considered to be hierarchical such that 'C<foo.bar>' |
| 194 |
would be a specific type of the more general 'C<foo>' type. |
| 195 |
|
| 196 |
=head1 METHODS |
| 197 |
|
| 198 |
=head2 type() |
| 199 |
|
| 200 |
Returns the exception type. |
| 201 |
|
| 202 |
=head2 info() |
| 203 |
|
| 204 |
Returns the exception information. |
| 205 |
|
| 206 |
=head1 AUTHOR |
| 207 |
|
| 208 |
Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/> |
| 209 |
|
| 210 |
=head1 COPYRIGHT |
| 211 |
|
| 212 |
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
| 213 |
|
| 214 |
This module is free software; you can redistribute it and/or |
| 215 |
modify it under the same terms as Perl itself. |
| 216 |
|
| 217 |
=head1 SEE ALSO |
| 218 |
|
| 219 |
L<Template>, L<Template::Context> |
| 220 |
|
| 221 |
=cut |
| 222 |
|
| 223 |
# Local Variables: |
| 224 |
# mode: perl |
| 225 |
# perl-indent-level: 4 |
| 226 |
# indent-tabs-mode: nil |
| 227 |
# End: |
| 228 |
# |
| 229 |
# vim: expandtab shiftwidth=4: |