1Class::Base(3) User Contributed Perl Documentation Class::Base(3)
2
6 Class::Base - useful base class for deriving other modules
7
9 version 0.09
10
12 package My::Funky::Module;
13 use base qw( Class::Base );
14 # custom initialiser method
16 sub init {
17 my ($self, $config) = @_;
18 # copy various params into $self
20 $self->params($config, qw( FOO BAR BAZ ))
21 || return undef;
22 # to indicate a failure
24 return $self->error('bad constructor!')
25 if $something_bad;
26 # or to indicate general happiness and well-being
28 return $self;
29 }
30 package main;
32 # new() constructor folds args into hash and calls init()
34 my $object = My::Funky::Module->new( foo => 'bar', ... )
35 || die My::Funky::Module->error();
36 # error() class/object method to get/set errors
38 $object->error('something has gone wrong');
39 print $object->error();
40 # debugging() method (de-)activates the debug() method
42 $object->debugging(1);
43 # debug() prints to STDERR if debugging enabled
45 $object->debug('The ', $animal, ' sat on the ', $place);
46
48 Please consider using Badger::Base instead which is the successor of
49 this module.
50 This module implements a simple base class from which other modules can
52 be derived, thereby inheriting a number of useful methods such as
53 "new()", "init()", "params()", "clone()", "error()" and "debug()".
54 For a number of years, I found myself re-writing this module for
56 practically every Perl project of any significant size. Or rather, I
57 would copy the module from the last project and perform a global search
58 and replace to change the names. Each time it got a little more
59 polished and eventually, I decided to Do The Right Thing and release it
60 as a module in it's own right.
61 It doesn't pretend to be an all-encompassing solution for every kind of
63 object creation problem you might encounter. In fact, it only supports
64 blessed hash references that are created using the popular, but by no
65 means universal convention of calling "new()" with a list or reference
66 to a hash array of named parameters. Constructor failure is indicated
67 by returning undef and setting the $ERROR package variable in the
68 module's class to contain a relevant message (which you can also fetch
69 by calling "error()" as a class method).
70 e.g.
72 my $object = My::Module->new(
74 file => 'myfile.html',
75 msg => 'Hello World'
76 ) || die $My::Module::ERROR;
77 or:
79 my $object = My::Module->new({
81 file => 'myfile.html',
82 msg => 'Hello World',
83 }) || die My::Module->error();
84 The "new()" method handles the conversion of a list of arguments into a
86 hash array and calls the "init()" method to perform any initialisation.
87 In many cases, it is therefore sufficient to define a module like so:
88 package My::Module;
90 use Class::Base;
91 use base qw( Class::Base );
92 sub init {
94 my ($self, $config) = @_;
95 # copy some config items into $self
96 $self->params($config, qw( FOO BAR )) || return undef;
97 return $self;
98 }
99 # ...plus other application-specific methods
101 1;
103 Then you can go right ahead and use it like this:
105 use My::Module;
107 my $object = My::Module->new( FOO => 'the foo value',
109 BAR => 'the bar value' )
110 || die $My::Module::ERROR;
111 Despite its limitations, Class::Base can be a surprisingly useful
113 module to have lying around for those times where you just want to
114 create a regular object based on a blessed hash reference and don't
115 want to worry too much about duplicating the same old code to bless a
116 hash, define configuration values, provide an error reporting
117 mechanism, and so on. Simply derive your module from "Class::Base" and
118 leave it to worry about most of the detail. And don't forget, you can
119 always redefine your own "new()", "error()", or other method, if you
120 don't like the way the Class::Base version works.
121 Subclassing Class::Base
123 This module is what object-oriented afficionados would describe as an
124 "abstract base class". That means that it's not designed to be used as
125 a stand-alone module, rather as something from which you derive your
126 own modules. Like this:
127 package My::Funky::Module
129 use base qw( Class::Base );
130 You can then use it like this:
132 use My::Funky::Module;
134 my $module = My::Funky::Module->new();
136 Construction and Initialisation Methods
138 If you want to apply any per-object initialisation, then simply write
139 an "init()" method. This gets called by the "new()" method which
140 passes a reference to a hash reference of configuration options.
141 sub init {
143 my ($self, $config) = @_;
144 ...
146 return $self;
148 }
149 When you create new objects using the "new()" method you can either
151 pass a hash reference or list of named arguments. The "new()" method
152 does the right thing to fold named arguments into a hash reference for
153 passing to the "init()" method. Thus, the following are equivalent:
154 # hash reference
156 my $module = My::Funky::Module->new({
157 foo => 'bar',
158 wiz => 'waz',
159 });
160 # list of named arguments (no enclosing '{' ... '}')
162 my $module = My::Funky::Module->new(
163 foo => 'bar',
164 wiz => 'waz'
165 );
166 Within the "init()" method, you can either handle the configuration
168 yourself:
169 sub init {
171 my ($self, $config) = @_;
172 $self->{ file } = $config->{ file }
174 || return $self->error('no file specified');
175 return $self;
177 }
178 or you can call the "params()" method to do it for you:
180 sub init {
182 my ($self, $config) = @_;
183 $self->params($config, 'file')
185 || return $self->error('no file specified');
186 return $self;
188 }
189 Error Handling
191 The "init()" method should return $self to indicate success or undef to
192 indicate a failure. You can use the "error()" method to report an
193 error within the "init()" method. The "error()" method returns undef,
194 so you can use it like this:
195 sub init {
197 my ($self, $config) = @_;
198 # let's make 'foobar' a mandatory argument
200 $self->{ foobar } = $config->{ foobar }
201 || return $self->error("no foobar argument");
202 return $self;
204 }
205 When you create objects of this class via "new()", you should now check
207 the return value. If undef is returned then the error message can be
208 retrieved by calling "error()" as a class method.
209 my $module = My::Funky::Module->new()
211 || die My::Funky::Module->error();
212 Alternately, you can inspect the $ERROR package variable which will
214 contain the same error message.
215 my $module = My::Funky::Module->new()
217 || die $My::Funky::Module::ERROR;
218 Of course, being a conscientious Perl programmer, you will want to be
220 sure that the $ERROR package variable is correctly defined.
221 package My::Funky::Module
223 use base qw( Class::Base );
224 our $ERROR;
226 You can also call "error()" as an object method. If you pass an
228 argument then it will be used to set the internal error message for the
229 object and return undef. Typically this is used within the module
230 methods to report errors.
231 sub another_method {
233 my $self = shift;
234 ...
236 # set the object error
238 return $self->error('something bad happened');
239 }
240 If you don't pass an argument then the "error()" method returns the
242 current error value. Typically this is called from outside the object
243 to determine its status. For example:
244 my $object = My::Funky::Module->new()
246 || die My::Funky::Module->error();
247 $object->another_method()
249 || die $object->error();
250 Debugging Methods
252 The module implements two methods to assist in writing debugging code:
253 debug() and debugging(). Debugging can be enabled on a per-object or
254 per-class basis, or as a combination of the two.
255 When creating an object, you can set the "DEBUG" flag (or lower case
257 "debug" if you prefer) to enable or disable debugging for that one
258 object.
259 my $object = My::Funky::Module->new( debug => 1 )
261 || die My::Funky::Module->error();
262 my $object = My::Funky::Module->new( DEBUG => 1 )
264 || die My::Funky::Module->error();
265 If you don't explicitly specify a debugging flag then it assumes the
267 value of the $DEBUG package variable in your derived class or 0 if that
268 isn't defined.
269 You can also switch debugging on or off via the "debugging()" method.
271 $object->debugging(0); # debug off
273 $object->debugging(1); # debug on
274 The "debug()" method examines the internal debugging flag (the "_DEBUG"
276 member within the $self hash) and if it finds it set to any true value
277 then it prints to STDERR all the arguments passed to it. The output is
278 prefixed by a tag containing the class name of the object in square
279 brackets (but see the "id()" method below for details on how to change
280 that value).
281 For example, calling the method as:
283 $object->debug('foo', 'bar');
285 prints the following output to STDERR:
287 [My::Funky::Module] foobar
289 When called as class methods, "debug()" and "debugging()" instead use
291 the $DEBUG package variable in the derived class as a flag to control
292 debugging. This variable also defines the default "DEBUG" flag for any
293 objects subsequently created via the new() method.
294 package My::Funky::Module
296 use base qw( Class::Base );
297 our $ERROR;
299 our $DEBUG = 0 unless defined $DEBUG;
300 # some time later, in a module far, far away
302 package main;
303 # debugging off (by default)
305 my $object1 = My::Funky::Module->new();
306 # turn debugging on for My::Funky::Module objects
308 $My::Funky::Module::DEBUG = 1;
309 # alternate syntax
311 My::Funky::Module->debugging(1);
312 # debugging on (implicitly from $DEBUG package var)
314 my $object2 = My::Funky::Module->new();
315 # debugging off (explicit override)
317 my $object3 = My::Funky::Module->new(debug => 0);
318 If you call "debugging()" without any arguments then it returns the
320 value of the internal object flag or the package variable accordingly.
321 print "debugging is turned ", $object->debugging() ? 'on' : 'off';
323
325 new()
326 Class constructor method which expects a reference to a hash array of
327 parameters or a list of "name => value" pairs which are automagically
328 folded into a hash reference. The method blesses a hash reference and
329 then calls the "init()" method, passing the reference to the hash array
330 of configuration parameters.
331 Returns a reference to an object on success or undef on error. In the
333 latter case, the "error()" method can be called as a class method, or
334 the $ERROR package variable (in the derived class' package) can be
335 inspected to return an appropriate error message.
336 my $object = My::Class->new( foo => 'bar' ) # params list
338 || die $My::Class::$ERROR; # package var
339 or
341 my $object = My::Class->new({ foo => 'bar' }) # params hashref
343 || die My::Class->error; # class method
344 init(\%config)
346 Object initialiser method which is called by the "new()" method,
347 passing a reference to a hash array of configuration parameters. The
348 method may be derived in a subclass to perform any initialisation
349 required. It should return $self on success, or "undef" on error, via
350 a call to the "error()" method.
351 package My::Module;
353 use base qw( Class::Base );
354 sub init {
356 my ($self, $config) = @_;
357 # let's make 'foobar' a mandatory argument
359 $self->{ foobar } = $config->{ foobar }
360 || return $self->error("no foobar argument");
361 return $self;
363 }
364 params($config, @keys)
366 The "params()" method accept a reference to a hash array as the first
367 argument containing configuration values such as those passed to the
368 "init()" method. The second argument can be a reference to a list of
369 parameter names or a reference to a hash array mapping parameter names
370 to default values. If the second argument is not a reference then all
371 the remaining arguments are taken as parameter names. Thus the method
372 can be called as follows:
373 sub init {
375 my ($self, $config) = @_;
376 # either...
378 $self->params($config, qw( foo bar ));
379 # or...
381 $self->params($config, [ qw( foo bar ) ]);
382 # or...
384 $self->params($config, { foo => 'default foo value',
385 bar => 'default bar value' } );
386 return $self;
388 }
389 The method looks for values in $config corresponding to the keys
391 specified and copies them, if defined, into $self.
392 Keys can be specified in UPPER CASE and the method will look for either
394 upper or lower case equivalents in the $config hash. Thus you can call
395 "params()" from "init()" like so:
396 sub init {
398 my ($self, $config) = @_;
399 $self->params($config, qw( FOO BAR ))
400 return $self;
401 }
402 but use either case for parameters passed to "new()":
404 my $object = My::Module->new( FOO => 'the foo value',
406 BAR => 'the bar value' )
407 || die My::Module->error();
408 my $object = My::Module->new( foo => 'the foo value',
410 bar => 'the bar value' )
411 || die My::Module->error();
412 Note however that the internal key within $self used to store the value
414 will be in the case provided in the call to "params()" (upper case in
415 this example). The method doesn't look for upper case equivalents when
416 they are specified in lower case.
417 When called in list context, the method returns a list of all the
419 values corresponding to the list of keys, some of which may be
420 undefined (allowing you to determine which values were successfully set
421 if you need to). When called in scalar context it returns a reference
422 to the same list.
423 clone()
425 The "clone()" method performs a simple shallow copy of the object hash
426 and creates a new object blessed into the same class. You may want to
427 provide your own "clone()" method to perform a more complex cloning
428 operation.
429 my $clone = $object->clone();
431 error($msg, ...)
433 General purpose method for getting and setting error messages. When
434 called as a class method, it returns the value of the $ERROR package
435 variable (in the derived class' package) if called without any
436 arguments, or sets the same variable when called with one or more
437 arguments. Multiple arguments are concatenated together.
438 # set error
440 My::Module->error('set the error string');
441 My::Module->error('set ', 'the ', 'error string');
442 # get error
444 print My::Module->error();
445 print $My::Module::ERROR;
446 When called as an object method, it operates on the "_ERROR" member of
448 the object, returning it when called without any arguments, or setting
449 it when called with arguments.
450 # set error
452 $object->error('set the error string');
453 # get error
455 print $object->error();
456 The method returns "undef" when called with arguments. This allows it
458 to be used within object methods as shown:
459 sub my_method {
461 my $self = shift;
462 # set error and return undef in one
464 return $self->error('bad, bad, error')
465 if $something_bad;
466 }
467 debug($msg, $msg, ...)
469 Prints all arguments to STDERR if the internal "_DEBUG" flag (when
470 called as an object method) or $DEBUG package variable (when called as
471 a class method) is set to a true value. Otherwise does nothing. The
472 output is prefixed by a string of the form "[Class::Name]" where the
473 name of the class is that returned by the "id()" method.
474 debugging($flag)
476 Used to get (no arguments) or set ($flag defined) the value of the
477 internal "_DEBUG" flag (when called as an object method) or $DEBUG
478 package variable (when called as a class method).
479 id($newid)
481 The "debug()" method calls this method to return an identifier for the
482 object for printing in the debugging message. By default it returns
483 the class name of the object (i.e. "ref $self"), but you can of course
484 subclass the method to return some other value. When called with an
485 argument it uses that value to set its internal "_ID" field which will
486 be returned by subsequent calls to "id()".
487
489 This module began life as the Template::Base module distributed as part
490 of the Template Toolkit.
491 Thanks to Brian Moseley and Matt Sergeant for suggesting various
493 enhancements, some of which went into version 0.02.
494 Version 0.04 was uploaded by Gabor Szabo.
496
498 • Andy Wardley <abw@kfs.org>
499 • Gabor Szabo <gabor@szabgab.com>
501 • Yanick Champoux <yanick@cpan.org>
503
505 This software is copyright (c) 2018, 2016, 2014, 2012 by Andy Wardley.
506 This is free software; you can redistribute it and/or modify it under
508 the same terms as the Perl 5 programming language system itself.
509perl v5.36.0 2022-07-22 Class::Base(3)