[Templates-cvs] cvs commit: TT3/lib/Template Base.pm
cvs@template-toolkit.org
cvs@template-toolkit.org
Mon, 13 Dec 2004 12:46:37 +0000
cvs 04/12/13 12:46:37
Modified: lib/Template Base.pm
Log:
* misc doc updates
Revision Changes Path
1.17 +36 -32 TT3/lib/Template/Base.pm
Index: Base.pm
===================================================================
RCS file: /template-toolkit/TT3/lib/Template/Base.pm,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- Base.pm 2004/12/13 12:27:09 1.16
+++ Base.pm 2004/12/13 12:46:36 1.17
@@ -16,7 +16,7 @@
# modify it under the same terms as Perl itself.
#
# REVISION
-# $Id: Base.pm,v 1.16 2004/12/13 12:27:09 abw Exp $
+# $Id: Base.pm,v 1.17 2004/12/13 12:46:36 abw Exp $
#
#========================================================================
@@ -29,7 +29,7 @@
require Template::Utils;
require Template::Exception;
-our $VERSION = sprintf("%d.%02d", q$Revision: 1.16 $ =~ /(\d+)\.(\d+)/);
+our $VERSION = sprintf("%d.%02d", q$Revision: 1.17 $ =~ /(\d+)\.(\d+)/);
our $DEBUG = 0 unless defined $DEBUG;
our $ERROR = '';
our $PAD = ' ';
@@ -611,15 +611,16 @@
=head1 SYNOPSIS
+ # define a subclass of Template::Base
package My::Template::Module;
use Template::Base;
use base qw( Template::Base );
+ # package vars for error reporting and debugging
our $ERROR = '';
our $DEBUG = 0 unless defined $DEBUG;
# define init() method for initialisation
-
sub init {
my ($self, $config)
@@ -636,7 +637,6 @@
package main;
# using the module
-
my $object = My::Template::Module->new( name => 'thingy' )
|| die My::Template::Module->error();
@@ -645,8 +645,7 @@
This module implements a base class object from which most (if not
all) of the other Template Toolkit modules are derived. It implements
a number of methods to aid in object creation and configuration, error
-reporting, debugging, and for loading and instantiating objects of
-other classes.
+reporting, and debugging.
=head1 METHODS
@@ -729,7 +728,7 @@
In the preceding example, the call to the C<error()> method
results in an exception object being throw via die with a C<type>
-of 'wibble' and <info> set to 'wibble is wobbling'.
+of 'wibble' and C<info> set to 'wibble is wobbling'.
See the C<error()> and C<throw()> methods for further details.
@@ -781,11 +780,11 @@
=head2 pkgvar($name, $default, $all)
-This method provides a convenient way to examine for the value of a
-scalar package variable. The first argument, C<$name>, provides the
-name of the variable in question (no leading C<$>). The second
-argument can be used to provide a default value to be used if the
-variable is undefined.
+This method provides a convenient way to examine the value of a scalar
+package variable. The first argument, C<$name>, provides the name of
+the variable in question (no leading C<$>, e.g. C<FOO> not C<$FOO>).
+The second argument can be used to provide a default value to be used
+if the variable is undefined.
sub init {
my ($self, $config) = @_;
@@ -839,9 +838,9 @@
returns an error.
Note that this method is provided in the short-term to ease the
-process of backward compatability with TT2. It may be deprecated in
+process of backward compatibility with TT2. It may be deprecated in
the future (or modified to use pkgvar()) and the current behaviour
-should not be relied upon as it may change.
+should not be relied upon.
=head2 error()
@@ -874,6 +873,10 @@
$object->engage()
|| die $object->error(); # warp drive number 3 is offline
+An exception object can also be passed as a single argument to the
+error method. In this case, the object is not "stringified" and is
+stored internally as it is.
+
The C<error()> method can also be called as a class method. In this
case, it updates and retrieves the C<$ERROR> package variable in the
package of the subclass module.
@@ -896,7 +899,7 @@
Here's an example showing how the C<throw> option can be set as
a constructor option.
- my frob = My::Template::Frobulator->new( throw => 'frob' );
+ my $frob = My::Template::Frobulator->new( throw => 'frob' );
Now when we call a method that raises an error via the C<error()> method,
it will be thrown as a Template::Exception object using Perl's die()
@@ -909,15 +912,15 @@
object error handling is defined.
$frob->something_that_generates_an_error()
- || die $object->error();
+ || die $frob->error();
Here's an example showing the C<$THROW> package variable being set
for a module.
package My::Template::Frobulator;
use base qw( Template::Base );
- use vars qw( $THROW );
- $THROW = 'frob';
+
+ our $THROW = 'frob';
sub something_that_generates_an_error {
my $self = shift;
@@ -980,12 +983,13 @@
$object->throw('an error has occurred');
# exception object
- $e = Template::Exception->new( engine => 'warp drive offline' );
+ $e = Template::Exception->new( type => 'engine',
+ info => '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.
+It can also be called with two arguments. The first defines the
+exception C<type>, the second the C<type> which provides an error
+message or other information relevant to the exception.
$object->throw( engine => 'warp drive offline' );
@@ -993,15 +997,14 @@
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 ) };
+ eval { $object->throw( engine => $e ) };
print "$@\n";
-In the example above, the C<$ee> exception already has a type of
+In the example above, the C<$e> 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
+to an overloaded stringification operator). This results in the
following output:
engine error - warp drive offline
@@ -1009,7 +1012,7 @@
If on the other hand we request that a C<propulsion> error is
throw:
- eval { $object->throw( propulsion => $ee );
+ eval { $object->throw( propulsion => $e );
Then instead we get a new C<propulsion> exception throw, with the
previous C<engine> exception linked in via the C<info> field.
@@ -1128,10 +1131,11 @@
}
}
-The method concatentates all arguments into a single string, stores it
-internally, and then returns C<undef>. The string should indicate a
-reason for declining a request (e.g. C<"thing not found: $name">)
-and can be subsequently retrieved via the C<declined()> method.
+The C<decline()> method concatentates all arguments into a single
+string, stores it internally, and then returns C<undef>. The string
+should indicate a reason for declining a request (e.g. C<"thing not
+found: $name">) and can be subsequently retrieved via the
+C<declined()> method.
=head2 declined()
@@ -1188,7 +1192,7 @@
=head1 VERSION
-$Revision: 1.16 $
+$Revision: 1.17 $
=head1 COPYRIGHT