local-lib5/lib/perl5/i486-linux-gnu-thread-multi/Template/Exception.pm

   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
  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>abw@wardley.orgE<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: