Debian Codegraph @

bench/perl/Template/Base.pm

raw
1 #============================================================= -*-perl-*-
2 #
3 # Template::Base
4 #
5 # DESCRIPTION
6 # Base class module implementing common functionality for various other
7 # Template Toolkit modules.
8 #
9 # AUTHOR
10 # Andy Wardley <[email protected]>
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::Base;
21
22 use strict;
23 use warnings;
24 use Template::Constants;
25
26 our $VERSION = 2.78;
27
28
29 #------------------------------------------------------------------------
30 # new(\%params)
31 #
32 # General purpose constructor method which expects a hash reference of
33 # configuration parameters, or a list of name => value pairs which are
34 # folded into a hash. Blesses a hash into an object and calls its
35 # _init() method, passing the parameter hash reference. Returns a new
36 # object derived from Template::Base, or undef on error.
37 #------------------------------------------------------------------------
38
39 sub new {
40 my $class = shift;
41 my ($argnames, @args, $arg, $cfg);
42 # $class->error(''); # always clear package $ERROR var?
43
44 { no strict 'refs';
45 no warnings 'once';
46 $argnames = \@{"$class\::BASEARGS"} || [ ];
47 }
48
49 # shift off all mandatory args, returning error if undefined or null
50 foreach $arg (@$argnames) {
51 return $class->error("no $arg specified")
52 unless ($cfg = shift);
53 push(@args, $cfg);
54 }
55
56 # fold all remaining args into a hash, or use provided hash ref
57 $cfg = defined $_[0] && ref($_[0]) eq 'HASH' ? shift : { @_ };
58
59 my $self = bless {
60 (map { ($_ => shift @args) } @$argnames),
61 _ERROR => '',
62 DEBUG => 0,
63 }, $class;
64
65 return $self->_init($cfg) ? $self : $class->error($self->error);
66 }
67
68
69 #------------------------------------------------------------------------
70 # error()
71 # error($msg, ...)
72 #
73 # May be called as a class or object method to set or retrieve the
74 # package variable $ERROR (class method) or internal member
75 # $self->{ _ERROR } (object method). The presence of parameters indicates
76 # that the error value should be set. Undef is then returned. In the
77 # abscence of parameters, the current error value is returned.
78 #------------------------------------------------------------------------
79
80 sub error {
81 my $self = shift;
82 my $errvar;
83
84 {
85 no strict qw( refs );
86 $errvar = ref $self ? \$self->{ _ERROR } : \${"$self\::ERROR"};
87 }
88 if (@_) {
89 $$errvar = ref($_[0]) ? shift : join('', @_);
90 return undef;
91 }
92 else {
93 return $$errvar;
94 }
95 }
96
97
98 #------------------------------------------------------------------------
99 # _init()
100 #
101 # Initialisation method called by the new() constructor and passing a
102 # reference to a hash array containing any configuration items specified
103 # as constructor arguments. Should return $self on success or undef on
104 # error, via a call to the error() method to set the error message.
105 #------------------------------------------------------------------------
106
107 sub _init {
108 my ($self, $config) = @_;
109 return $self;
110 }
111
112
113 sub debug {
114 my $self = shift;
115 my $msg = join('', @_);
116 my ($pkg, $file, $line) = caller();
117
118 unless ($msg =~ /\n$/) {
119 $msg .= ($self->{ DEBUG } & Template::Constants::DEBUG_CALLER)
120 ? " at $file line $line\n"
121 : "\n";
122 }
123
124 print STDERR "[$pkg] $msg";
125 }
126
127
128 #------------------------------------------------------------------------
129 # module_version()
130 #
131 # Returns the current version number.
132 #------------------------------------------------------------------------
133
134 sub module_version {
135 my $self = shift;
136 my $class = ref $self || $self;
137 no strict 'refs';
138 return ${"${class}::VERSION"};
139 }
140
141
142 1;
143
144 __END__
145
146 =head1 NAME
147
148 Template::Base - Base class module implementing common functionality
149
150 =head1 SYNOPSIS
151
152 package My::Module;
153 use base qw( Template::Base );
154
155 sub _init {
156 my ($self, $config) = @_;
157 $self->{ doodah } = $config->{ doodah }
158 || return $self->error("No 'doodah' specified");
159 return $self;
160 }
161
162 package main;
163
164 my $object = My::Module->new({ doodah => 'foobar' })
165 || die My::Module->error();
166
167 =head1 DESCRIPTION
168
169 Base class module which implements a constructor and error reporting
170 functionality for various Template Toolkit modules.
171
172 =head1 PUBLIC METHODS
173
174 =head2 new(\%config)
175
176 Constructor method which accepts a reference to a hash array or a list
177 of C<name =E<gt> value> parameters which are folded into a hash. The
178 C<_init()> method is then called, passing the configuration hash and should
179 return true/false to indicate success or failure. A new object reference
180 is returned, or undef on error. Any error message raised can be examined
181 via the L<error()> class method or directly via the C<$ERROR> package variable
182 in the derived class.
183
184 my $module = My::Module->new({ ... })
185 || die My::Module->error(), "\n";
186
187 my $module = My::Module->new({ ... })
188 || die "constructor error: $My::Module::ERROR\n";
189
190 =head2 error($msg, ...)
191
192 May be called as an object method to get/set the internal C<_ERROR> member
193 or as a class method to get/set the C<$ERROR> variable in the derived class's
194 package.
195
196 my $module = My::Module->new({ ... })
197 || die My::Module->error(), "\n";
198
199 $module->do_something()
200 || die $module->error(), "\n";
201
202 When called with parameters (multiple params are concatenated), this
203 method will set the relevant variable and return undef. This is most
204 often used within object methods to report errors to the caller.
205
206 package My::Module;
207
208 sub foobar {
209 my $self = shift;
210
211 # some other code...
212
213 return $self->error('some kind of error...')
214 if $some_condition;
215 }
216
217 =head2 debug($msg, ...)
218
219 Generates a debugging message by concatenating all arguments
220 passed into a string and printing it to C<STDERR>. A prefix is
221 added to indicate the module of the caller.
222
223 package My::Module;
224
225 sub foobar {
226 my $self = shift;
227
228 $self->debug('called foobar()');
229
230 # some other code...
231 }
232
233 When the C<foobar()> method is called, the following message
234 is sent to C<STDERR>:
235
236 [My::Module] called foobar()
237
238 Objects can set an internal C<DEBUG> value which the C<debug()>
239 method will examine. If this value sets the relevant bits
240 to indicate C<DEBUG_CALLER> then the file and line number of
241 the caller will be appened to the message.
242
243 use Template::Constants qw( :debug );
244
245 my $module = My::Module->new({
246 DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER,
247 });
248
249 $module->foobar();
250
251 This generates an error message such as:
252
253 [My::Module] called foobar() at My/Module.pm line 6
254
255 =head2 module_version()
256
257 Returns the version number for a module, as defined by the C<$VERSION>
258 package variable.
259
260 =head1 AUTHOR
261
262 Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/>
263
264 =head1 COPYRIGHT
265
266 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
267
268 This module is free software; you can redistribute it and/or
269 modify it under the same terms as Perl itself.
270
271 =head1 SEE ALSO
272
273 L<Template>
274
275 =cut
276
277 # Local Variables:
278 # mode: perl
279 # perl-indent-level: 4
280 # indent-tabs-mode: nil
281 # End:
282 #
283 # vim: expandtab shiftwidth=4: