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