[Templates-cvs] cvs commit: TT3/lib/Template Base.pm
cvs@template-toolkit.org
cvs@template-toolkit.org
Thu, 25 Mar 2004 09:56:25 +0000
cvs 04/03/25 09:56:25
Modified: lib/Template Base.pm
Log:
* updated throw() method and docs
Revision Changes Path
1.4 +112 -26 TT3/lib/Template/Base.pm
Index: Base.pm
===================================================================
RCS file: /template-toolkit/TT3/lib/Template/Base.pm,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Base.pm 2004/03/24 15:53:26 1.3
+++ Base.pm 2004/03/25 09:56:25 1.4
@@ -18,7 +18,7 @@
# modify it under the same terms as Perl itself.
#
# REVISION
-# $Id: Base.pm,v 1.3 2004/03/24 15:53:26 abw Exp $
+# $Id: Base.pm,v 1.4 2004/03/25 09:56:25 abw Exp $
#
#========================================================================
@@ -33,7 +33,7 @@
require Template::Utils;
require Template::Exception;
-$VERSION = sprintf("%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/);
+$VERSION = sprintf("%d.%02d", q$Revision: 1.4 $ =~ /(\d+)\.(\d+)/);
$DEBUG = 0 unless defined $DEBUG;
$ERROR = '';
$PAD = 2;
@@ -185,7 +185,7 @@
#
# Returns current error when called without args. When called with
# args they are concatenated to define a new error string which is set
-# in the object error item and/or the $ERROR package variable. A
+# in the object ERROR item and/or the $ERROR package variable. A
# single reference argument (e.g. an exception object) can be passed
# as an argument. This is used as is without being first stringified.
# If the THROW item is set then the error is thrown via throw().
@@ -210,7 +210,7 @@
$self->{ ERROR } = $error;
$self->{ DECLINED } = 0;
- # look for errors action in object, then package
+ # look for throw action in object, then package
$throw = exists $self->{ THROW }
? $self->{ THROW }
: ${"$class\::THROW"};
@@ -222,7 +222,6 @@
# throw error or return undef/0 value of $throw
if ($throw) {
- $error .= "\n" unless $error =~ /\n$/;
return $self->throw($throw, $error);
}
else {
@@ -238,6 +237,60 @@
}
+
+#------------------------------------------------------------------------
+# throw($error)
+# throw($type, $error)
+# throw($type, $error, @args)
+#
+# This method throws an exception by calling die(). It can be called with
+# one passed an
+# exception object, or an error message which will be upgraded to
+#------------------------------------------------------------------------
+
+sub throw {
+ my $self = shift;
+
+ if (@_ == 1) {
+ # if we got one argument then it's either an exception object
+ # which can be throw, or an error message which is first
+ # upgraded to an 'undef' exception
+
+ if (UNIVERSAL::isa($_[0], $EXCEPTION)) {
+ die $_[0];
+ }
+ else {
+ die $EXCEPTION->new(undef => $_[0]);
+ }
+ }
+ elsif (@_ == 2) {
+ # if we got two arguments then it's either type and info, which
+ # we turn into an exception, or it's a type and exception object.
+ # in this case we throw the existing exception if it has the same
+ # type as the one we're expecting to throw, otherwise we create
+ # a new exception and pass the old one as the info field
+
+ if ( UNIVERSAL::isa($_[1], $EXCEPTION) && $_[1]->type() eq $_[0]) {
+ die $_[1];
+ }
+ else {
+ die $EXCEPTION->new(@_);
+ }
+ }
+ elsif (@_) {
+ # if we get more than two arguments then we need to create a new
+ # exception to store the extra arguments, regardless of whether
+ # or not any exception object passed already has the correct type.
+ die $EXCEPTION->new(@_);
+ }
+ else {
+ die "throw() called without any arguments\n";
+ }
+}
+
+
+
+
#------------------------------------------------------------------------
# warning()
# warning($msg1, $msg2, $msg3, ...)
@@ -342,26 +395,6 @@
#------------------------------------------------------------------------
-# throw()
-#
-# This method is only here temporarily. It might get moved, it might
-# get implemented properly. TBA.
-#------------------------------------------------------------------------
-
-sub throw {
- my $self = shift;
-
- if (@_ == 1 && UNIVERSAL::isa($_[0], $EXCEPTION)) {
- # only argument is an exception so re-throw it
- die $_[0];
- }
- else {
- die $EXCEPTION->new(@_);
- }
-}
-
-
-#------------------------------------------------------------------------
# module($name, $config)
#
# Load a module. The $name passed should correspond to an object item
@@ -868,6 +901,59 @@
# error thrown as 'frobless'
my $frob = My::Template::Frobulator->new( throw => 'frobless' );
+=head2 throw()
+
+This method throws an exception by calling die(). It can be called
+with one argument, which can either be a Template::Exception object
+(or subclass), or an error message which is upgraded into an exception
+with the type set to 'undef' (that's the literal string "undef" rather
+than the undefined value).
+
+ # error message
+ $object->throw('an error has occurred');
+
+ # exception object
+ $e = Template::Exception->new( engine => 'warp drive offline' );
+ $object->throw($e);
+
+It can also be called with two arguments. The first defines the
+exception type, the second the error message or other information
+relevant to the exception.
+
+ $object->throw( engine => 'warp drive offline' );
+
+The second argument can also be a Template::Exception object. If the
+exception has the same type as the first argument, then it is left
+unchanged and is thrown as is.
+
+ $ee = Template::Exception->new( engine => 'warp drive offline' );
+ eval { $object->throw( engine => $ee ) };
+ print "$@\n";
+
+In the example above, the C<$ee> exception already has a type of
+C<engine> and so is thrown without change. By enclosing the call to
+C<throw()> in an C<eval> block, we can catch the exception thrown in
+C<$@> and print it, causing its C<text()> method to be called (thanks
+to an overloaded stringification operator). This result in the
+following output:
+
+ engine error - warp drive offline
+
+If on the other hand we request that a C<propulsion> error is
+throw:
+
+ eval { $object->throw( propulsion => $ee );
+
+Then instead we get a new C<propulsion> exception throw, with the
+previous C<engine> exception linked in via the C<info> field.
+This generates the following output:
+
+ propulsion error - engine error - warp drive offline
+
+By this mechanism, exceptions can be nested inside each other to
+allow as much (or as little) information about the cause of an
+error to be recorded.
+
=head2 warning()
This method is very similar to C<error()> described above. However,
@@ -1000,7 +1086,7 @@
=head1 VERSION
-$Revision: 1.3 $
+$Revision: 1.4 $
=head1 COPYRIGHT