[Templates-cvs] cvs commit: TT3/lib/Template/Toolkit Base.pm
cvs@template-toolkit.org
cvs@template-toolkit.org
Wed, 03 Dec 2003 14:52:19 +0000
cvs 03/12/03 14:52:19
Modified: lib/Template/Toolkit Base.pm
Log:
* updated docs
Revision Changes Path
1.2 +197 -10 TT3/lib/Template/Toolkit/Base.pm
Index: Base.pm
===================================================================
RCS file: /template-toolkit/TT3/lib/Template/Toolkit/Base.pm,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Base.pm 2003/12/03 14:04:14 1.1
+++ Base.pm 2003/12/03 14:52:18 1.2
@@ -17,7 +17,7 @@
# modify it under the same terms as Perl itself.
#
# REVISION
-# $Id: Base.pm,v 1.1 2003/12/03 14:04:14 abw Exp $
+# $Id: Base.pm,v 1.2 2003/12/03 14:52:18 abw Exp $
#
#========================================================================
@@ -26,14 +26,9 @@
use strict;
use warnings;
-#use Template::Toolkit::Utils; # TODO
-#use Template::Toolkit::Debug; # TODO
+use vars qw( $VERSION $DEBUG $ERROR $WARNING );
-use vars qw( $VERSION $DEBUG $ERROR );
-#use base qw( Template::Toolkit::Debug );
-
-# $UTILS = 'Template::Toolkit::Utils';
-$VERSION = sprintf("%d.%02d", q$Revision: 1.1 $ =~ /(\d+)\.(\d+)/);
+$VERSION = sprintf("%d.%02d", q$Revision: 1.2 $ =~ /(\d+)\.(\d+)/);
$DEBUG = 0 unless defined $DEBUG;
$ERROR = '';
@@ -161,7 +156,7 @@
}
else {
my $warnings = $self->warning();
- return wantarray ? @$warnings : $warnings;
+ return @$warnings;
}
}
@@ -194,7 +189,199 @@
=head1 METHODS
-# TODO
+=head2 new()
+
+This is a general purpose constructor method. It accepts either a
+reference to a hash array of named parameters (or an object derived
+from a hash array), or a list of named parameters which are then
+folded into a hash reference.
+
+ # hash reference of named params
+ my $object = My::Template::Module->new({
+ arg1 => 'value1',
+ arg2 => 'value2',
+ ...etc...
+ });
+
+ # list of named params
+ my $object = My::Template::Module->new(
+ arg1 => 'value1',
+ arg2 => 'value2',
+ ...etc...
+ );
+
+The constructor creates a new object by blessing a hash reference
+and then calls the C<init()> method, passing the reference to the
+hash array of named parameters.
+
+The C<new()> method returns whatever the C<init()> method returns
+(usually the C<$self> reference, but it can actually be something
+else). If C<init()> doesn't return a true value then the C<new()>
+method will return C<undef>. The C<error()> method can then be
+called to determine the cause of the problem.
+
+ my $object = My::Template::Module->new()
+ || die My::Template::Module->error();
+
+Constructor errors can also be examined via the C<$ERROR> package
+variable. Note that this is in the package of the subclass module,
+not in C<Template::Toolkit::Base>.
+
+ my $object = My::Template::Module->new()
+ || die $My::Template::Module::ERROR;
+
+=head2 init()
+
+This initialisation method is called by the C<new()> constructor method.
+It is passed a reference to a hash array of named parameters. The
+method may perform any configuration or initialisation processes and
+should then return the C<$self> reference to inidicate success.
+
+ sub init {
+ my ($self, $config) = @_;
+
+ # set the 'answer' parameter or default to 42
+ $self->{ answer } = $config->{ answer } || 42;
+
+ return $self;
+ }
+
+The C<init()> method can actually return any true value. Whatever
+it returns is what gets passed back to the user from the C<new()>
+method. That's why you nearly always want to pass C<$self> back.
+However, there are certain cases (e.g. plugins) where object
+constructors don't return an object at all, just something that is
+constructed like one.
+
+If something goes wrong in the C<init()> method then you should
+call the C<error()> method and return C<undef>. The C<error()>
+method returns C<undef> when you pass it an argument, so you
+can use it as follows:
+
+ sub init {
+ my ($self, $config) = @_;
+
+ # set the 'answer' parameter or report error
+ $self->{ answer } = $config->{ answer }
+ || return $self->error('no answer supplied');
+
+ return $self;
+ }
+
+=head2 error()
+
+The C<error()> method is used for error reporting. When an object method
+fails for some reason, it calls the C<error()> method passing an argument
+denoting the problem that occurred.
+
+ sub engage {
+ my $self = shift;
+ return $self->error('warp drive offline');
+ }
+
+Multiple arguments can be passed to the C<error()> method. They are
+concatenated into a single string.
+
+ sub engage {
+ my $self = shift;
+ return $self->error( 'warp drive number ',
+ $self->{ engine_no },
+ ' is offline' );
+ }
+
+When the C<engage()> method is called, the C<undef> value returned
+indicates that an error has occurred. The C<error()> method can then
+be called again, this time without any arguments, to retrieve the
+error message.
+
+ $object->engage()
+ || die $object->error(); # warp drive number 3 is offline
+
+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.
+
+ # calling package error() method
+ my $object = My::Template::Module->new()
+ || die My::Template::Module->error();
+
+ # accessing $ERROR package variable
+ my $object = My::Template::Module->new()
+ || die $My::Template::Module::ERROR;
+
+=head2 warning()
+
+This method is very similar to C<error()> described above. However,
+while an object can only report one error at any time (we assume that
+an error is a "fatal" condition which requires the object to return
+right away), it can report any number of non-fatal warnings. The
+C<warning()> method maintains a list of warnings inside the object
+or in the C<$WARNINGS> package variable (a reference to a list) when
+called as a class method.
+
+When called with arguments, the C<warning()> method concatentates
+them into a single string and adds it to the current warnings list.
+
+ sub disengage {
+ my $self = shift;
+
+ $self->warning('warp drive already offline')
+ unless $self->{ engaged };
+
+ # ...etc...
+
+ return 1;
+ }
+
+When called in this way, the C<warning()> method returns C<0> (in contrast
+to the C<error()> method which returns C<undef>). So you might choose
+to write your method like this:
+
+ sub disengage {
+ my $self = shift;
+
+ return $self->warning('warp drive already offline')
+ unless $self->{ engaged };
+
+ # ...etc...
+
+ return 1;
+ }
+
+And call it like this:
+
+ defined $object->disengage()
+ || die $object->error();
+
+When you call the warning() method without any arguments, it returns
+a reference to a list of current warnings.
+
+ my $warnings = $object->warning();
+ if (@$warnings) {
+ warn "warning while disengaging warp drive: ", @$warnings;
+ }
+
+=head2 warnings()
+
+When called with arguments, this method calls the C<warning()> method once
+for each argument. Thus the following examples are equivalent.
+
+ # single call to warnings()
+ $object->warnings('foo', 'bar', 'baz');
+
+ # multiple calls to warning()
+ $object->warning('foo');
+ $object->warning('bar');
+ $object->warning('baz');
+
+When called without arguments, the C<warnings()> method returns a
+list of warnings (rather than the reference to a list of warnings
+that C<warning()> returns).
+
+ if ($object->warnings()) {
+ die "warning while disengaging warp drive: ",
+ $object->warnings();
+ }
=head1 AUTHOR