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 <abw@wardley.org> 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 20package Template::Exception; 21 22use strict; 23use warnings; 24use constant TYPE => 0; 25use constant INFO => 1; 26use constant TEXT => 2; 27use overload q|""| => "as_string", fallback => 1; 28 29our $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 45sub 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 59sub type { 60 $_[0]->[ TYPE ]; 61} 62 63sub info { 64 $_[0]->[ INFO ]; 65} 66 67sub 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 84sub 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 109sub 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 124sub 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 1401; 141 142__END__ 143 144=head1 NAME 145 146Template::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 163The C<Template::Exception> module defines an object class for 164representing exceptions within the template processing life cycle. 165Exceptions can be raised by modules within the Template Toolkit, or 166can be generated and returned by user code bound to template 167variables. 168 169Exceptions can be raised in a template using the C<THROW> directive, 170 171 [% THROW user.login 'no user id: please login' %] 172 173or by calling the L<throw()|Template::Context#throw()> method on the current 174L<Template::Context> object, 175 176 $context->throw('user.passwd', 'Incorrect Password'); 177 $context->throw('Incorrect Password'); # type 'undef' 178 179or 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 183or by simply calling C<die()> with an error string. This is 184automagically caught and converted to an exception of 'C<undef>' 185type (that's the literal string 'C<undef>' rather than Perl's 186undefined value) which can then be handled in the usual way. 187 188 die "I'm sorry Dave, I can't do that"; 189 190Each exception is defined by its type and a information component 191(e.g. error message). The type can be any identifying string and may 192contain dotted components (e.g. 'C<foo>', 'C<foo.bar>', 'C<foo.bar.baz>'). 193Exception types are considered to be hierarchical such that 'C<foo.bar>' 194would be a specific type of the more general 'C<foo>' type. 195 196=head1 METHODS 197 198=head2 type() 199 200Returns the exception type. 201 202=head2 info() 203 204Returns the exception information. 205 206=head1 AUTHOR 207 208Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> 209 210=head1 COPYRIGHT 211 212Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. 213 214This module is free software; you can redistribute it and/or 215modify it under the same terms as Perl itself. 216 217=head1 SEE ALSO 218 219L<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: 230