local-lib5/man/man3/Template::Exception.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Exception 3"
 132 .TH Template::Exception 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Exception \- Exception handling class module
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Template::Exception;
 139 .Ve
 140 .PP
 141 .Vb 4
 142 \&    my $exception = Template::Exception\->new($type, $info);
 143 \&    $type = $exception\->type;
 144 \&    $info = $exception\->info;
 145 \&    ($type, $info) = $exception\->type_info;
 146 .Ve
 147 .PP
 148 .Vb 1
 149 \&    print $exception\->as_string();
 150 .Ve
 151 .PP
 152 .Vb 1
 153 \&    $handler = $exception\->select_handler(\e@candidates);
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 The \f(CW\*(C`Template::Exception\*(C'\fR module defines an object class for
 158 representing exceptions within the template processing life cycle.
 159 Exceptions can be raised by modules within the Template Toolkit, or
 160 can be generated and returned by user code bound to template
 161 variables.
 162 .PP
 163 Exceptions can be raised in a template using the \f(CW\*(C`THROW\*(C'\fR directive,
 164 .PP
 165 .Vb 1
 166 \&    [% THROW user.login 'no user id: please login' %]
 167 .Ve
 168 .PP
 169 or by calling the \fIthrow()\fR method on the current
 170 Template::Context object,
 171 .PP
 172 .Vb 2
 173 \&    $context\->throw('user.passwd', 'Incorrect Password');
 174 \&    $context\->throw('Incorrect Password');    # type 'undef'
 175 .Ve
 176 .PP
 177 or from Perl code by calling \f(CW\*(C`die()\*(C'\fR with a \f(CW\*(C`Template::Exception\*(C'\fR object,
 178 .PP
 179 .Vb 1
 180 \&    die (Template::Exception\->new('user.denied', 'Invalid User ID'));
 181 .Ve
 182 .PP
 183 or by simply calling \f(CW\*(C`die()\*(C'\fR with an error string.  This is
 184 automagically caught and converted to an  exception of '\f(CW\*(C`undef\*(C'\fR'
 185 type (that's the literal string '\f(CW\*(C`undef\*(C'\fR' rather than Perl's
 186 undefined value) which can then be handled in the usual way.
 187 .PP
 188 .Vb 1
 189 \&    die "I'm sorry Dave, I can't do that";
 190 .Ve
 191 .PP
 192 Each exception is defined by its type and a information component
 193 (e.g. error message).  The type can be any identifying string and may
 194 contain dotted components (e.g. '\f(CW\*(C`foo\*(C'\fR', '\f(CW\*(C`foo.bar\*(C'\fR', '\f(CW\*(C`foo.bar.baz\*(C'\fR').
 195 Exception types are considered to be hierarchical such that '\f(CW\*(C`foo.bar\*(C'\fR'
 196 would be a specific type of the more general '\f(CW\*(C`foo\*(C'\fR' type.
 197 .SH "METHODS"
 198 .IX Header "METHODS"
 199 .Sh "\fItype()\fP"
 200 .IX Subsection "type()"
 201 Returns the exception type.
 202 .Sh "\fIinfo()\fP"
 203 .IX Subsection "info()"
 204 Returns the exception information.
 205 .SH "AUTHOR"
 206 .IX Header "AUTHOR"
 207 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 208 .SH "COPYRIGHT"
 209 .IX Header "COPYRIGHT"
 210 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 211 .PP
 212 This module is free software; you can redistribute it and/or
 213 modify it under the same terms as Perl itself.
 214 .SH "SEE ALSO"
 215 .IX Header "SEE ALSO"
 216 Template, Template::Context