This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Mention of possible use of a scalar variable on the rhs of an arrow "->"
[perl5.git] / pod / perlobj.pod
CommitLineData
a0d0e21e 1=head1 NAME
d74e8afc 2X<object> X<OOP>
a0d0e21e
LW
3
4perlobj - Perl objects
5
6=head1 DESCRIPTION
7
14218588 8First you need to understand what references are in Perl.
5f05dabc
PP
9See L<perlref> for that. Second, if you still find the following
10reference work too complicated, a tutorial on object-oriented programming
890a53b9 11in Perl can be found in L<perltoot> and L<perltooc>.
a0d0e21e 12
54310121 13If you're still with us, then
5f05dabc 14here are three very simple definitions that you should find reassuring.
a0d0e21e
LW
15
16=over 4
17
18=item 1.
19
20An object is simply a reference that happens to know which class it
21belongs to.
22
23=item 2.
24
25A class is simply a package that happens to provide methods to deal
26with object references.
27
28=item 3.
29
30A method is simply a subroutine that expects an object reference (or
55497cff 31a package name, for class methods) as the first argument.
a0d0e21e
LW
32
33=back
34
35We'll cover these points now in more depth.
36
37=head2 An Object is Simply a Reference
d74e8afc 38X<object> X<bless> X<constructor> X<new>
a0d0e21e
LW
39
40Unlike say C++, Perl doesn't provide any special syntax for
41constructors. A constructor is merely a subroutine that returns a
cb1a09d0 42reference to something "blessed" into a class, generally the
a0d0e21e
LW
43class that the subroutine is defined in. Here is a typical
44constructor:
45
46 package Critter;
47 sub new { bless {} }
48
5a964f20
TC
49That word C<new> isn't special. You could have written
50a construct this way, too:
51
52 package Critter;
53 sub spawn { bless {} }
54
14218588 55This might even be preferable, because the C++ programmers won't
5a964f20
TC
56be tricked into thinking that C<new> works in Perl as it does in C++.
57It doesn't. We recommend that you name your constructors whatever
58makes sense in the context of the problem you're solving. For example,
59constructors in the Tk extension to Perl are named after the widgets
60they create.
61
62One thing that's different about Perl constructors compared with those in
63C++ is that in Perl, they have to allocate their own memory. (The other
64things is that they don't automatically call overridden base-class
65constructors.) The C<{}> allocates an anonymous hash containing no
66key/value pairs, and returns it The bless() takes that reference and
67tells the object it references that it's now a Critter, and returns
68the reference. This is for convenience, because the referenced object
69itself knows that it has been blessed, and the reference to it could
70have been returned directly, like this:
a0d0e21e
LW
71
72 sub new {
73 my $self = {};
74 bless $self;
75 return $self;
76 }
77
14218588 78You often see such a thing in more complicated constructors
a0d0e21e
LW
79that wish to call methods in the class as part of the construction:
80
81 sub new {
5a964f20 82 my $self = {};
a0d0e21e
LW
83 bless $self;
84 $self->initialize();
cb1a09d0
AD
85 return $self;
86 }
87
1fef88e7 88If you care about inheritance (and you should; see
b687b08b 89L<perlmodlib/"Modules: Creation, Use, and Abuse">),
1fef88e7 90then you want to use the two-arg form of bless
cb1a09d0
AD
91so that your constructors may be inherited:
92
93 sub new {
94 my $class = shift;
95 my $self = {};
5a964f20 96 bless $self, $class;
cb1a09d0
AD
97 $self->initialize();
98 return $self;
99 }
100
c47ff5f1 101Or if you expect people to call not just C<< CLASS->new() >> but also
eac7fe86
O
102C<< $obj->new() >>, then use something like the following. (Note that using
103this to call new() on an instance does not automatically perform any
104copying. If you want a shallow or deep copy of an object, you'll have to
105specifically allow for that.) The initialize() method used will be of
106whatever $class we blessed the object into:
cb1a09d0
AD
107
108 sub new {
109 my $this = shift;
110 my $class = ref($this) || $this;
111 my $self = {};
5a964f20 112 bless $self, $class;
cb1a09d0
AD
113 $self->initialize();
114 return $self;
a0d0e21e
LW
115 }
116
117Within the class package, the methods will typically deal with the
118reference as an ordinary reference. Outside the class package,
119the reference is generally treated as an opaque value that may
5f05dabc 120be accessed only through the class's methods.
a0d0e21e 121
14218588 122Although a constructor can in theory re-bless a referenced object
19799a22
GS
123currently belonging to another class, this is almost certainly going
124to get you into trouble. The new class is responsible for all
125cleanup later. The previous blessing is forgotten, as an object
126may belong to only one class at a time. (Although of course it's
127free to inherit methods from many classes.) If you find yourself
128having to do this, the parent class is probably misbehaving, though.
a0d0e21e
LW
129
130A clarification: Perl objects are blessed. References are not. Objects
131know which package they belong to. References do not. The bless()
5f05dabc 132function uses the reference to find the object. Consider
a0d0e21e
LW
133the following example:
134
135 $a = {};
136 $b = $a;
137 bless $a, BLAH;
138 print "\$b is a ", ref($b), "\n";
139
54310121 140This reports $b as being a BLAH, so obviously bless()
a0d0e21e
LW
141operated on the object and not on the reference.
142
143=head2 A Class is Simply a Package
d74e8afc 144X<class> X<package> X<@ISA> X<inheritance>
a0d0e21e
LW
145
146Unlike say C++, Perl doesn't provide any special syntax for class
5f05dabc 147definitions. You use a package as a class by putting method
a0d0e21e
LW
148definitions into the class.
149
5a964f20 150There is a special array within each package called @ISA, which says
a0d0e21e
LW
151where else to look for a method if you can't find it in the current
152package. This is how Perl implements inheritance. Each element of the
153@ISA array is just the name of another package that happens to be a
154class package. The classes are searched (depth first) for missing
155methods in the order that they occur in @ISA. The classes accessible
54310121 156through @ISA are known as base classes of the current class.
a0d0e21e 157
5a964f20
TC
158All classes implicitly inherit from class C<UNIVERSAL> as their
159last base class. Several commonly used methods are automatically
160supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for
161more details.
d74e8afc 162X<UNIVERSAL> X<base class> X<class, base>
5a964f20 163
14218588 164If a missing method is found in a base class, it is cached
a0d0e21e
LW
165in the current class for efficiency. Changing @ISA or defining new
166subroutines invalidates the cache and causes Perl to do the lookup again.
167
5a964f20
TC
168If neither the current class, its named base classes, nor the UNIVERSAL
169class contains the requested method, these three places are searched
170all over again, this time looking for a method named AUTOLOAD(). If an
171AUTOLOAD is found, this method is called on behalf of the missing method,
172setting the package global $AUTOLOAD to be the fully qualified name of
173the method that was intended to be called.
d74e8afc 174X<AUTOLOAD>
5a964f20
TC
175
176If none of that works, Perl finally gives up and complains.
177
ed850460 178If you want to stop the AUTOLOAD inheritance say simply
d74e8afc 179X<AUTOLOAD>
ed850460
JH
180
181 sub AUTOLOAD;
182
183and the call will die using the name of the sub being called.
184
5a964f20
TC
185Perl classes do method inheritance only. Data inheritance is left up
186to the class itself. By and large, this is not a problem in Perl,
187because most classes model the attributes of their object using an
188anonymous hash, which serves as its own little namespace to be carved up
189by the various classes that might want to do something with the object.
190The only problem with this is that you can't sure that you aren't using
191a piece of the hash that isn't already used. A reasonable workaround
192is to prepend your fieldname in the hash with the package name.
d74e8afc 193X<inheritance, method> X<inheritance, data>
5a964f20
TC
194
195 sub bump {
196 my $self = shift;
197 $self->{ __PACKAGE__ . ".count"}++;
198 }
a0d0e21e
LW
199
200=head2 A Method is Simply a Subroutine
d74e8afc 201X<method>
a0d0e21e
LW
202
203Unlike say C++, Perl doesn't provide any special syntax for method
204definition. (It does provide a little syntax for method invocation
205though. More on that later.) A method expects its first argument
19799a22
GS
206to be the object (reference) or package (string) it is being invoked
207on. There are two ways of calling methods, which we'll call class
208methods and instance methods.
a0d0e21e 209
55497cff 210A class method expects a class name as the first argument. It
19799a22
GS
211provides functionality for the class as a whole, not for any
212individual object belonging to the class. Constructors are often
890a53b9 213class methods, but see L<perltoot> and L<perltooc> for alternatives.
19799a22
GS
214Many class methods simply ignore their first argument, because they
215already know what package they're in and don't care what package
5f05dabc 216they were invoked via. (These aren't necessarily the same, because
55497cff
PP
217class methods follow the inheritance tree just like ordinary instance
218methods.) Another typical use for class methods is to look up an
a0d0e21e
LW
219object by name:
220
221 sub find {
222 my ($class, $name) = @_;
223 $objtable{$name};
224 }
225
55497cff 226An instance method expects an object reference as its first argument.
a0d0e21e
LW
227Typically it shifts the first argument into a "self" or "this" variable,
228and then uses that as an ordinary reference.
229
230 sub display {
231 my $self = shift;
232 my @keys = @_ ? @_ : sort keys %$self;
233 foreach $key (@keys) {
234 print "\t$key => $self->{$key}\n";
235 }
236 }
237
238=head2 Method Invocation
d74e8afc 239X<invocation> X<method> X<arrow> X<< -> >>
a0d0e21e 240
5d9f8747
IK
241For various historical and other reasons, Perl offers two equivalent
242ways to write a method call. The simpler and more common way is to use
243the arrow notation:
a0d0e21e 244
5d9f8747
IK
245 my $fred = Critter->find("Fred");
246 $fred->display("Height", "Weight");
a0d0e21e 247
5f7b1de2 248You should already be familiar with the use of the C<< -> >> operator with
5d9f8747
IK
249references. In fact, since C<$fred> above is a reference to an object,
250you could think of the method call as just another form of
251dereferencing.
a0d0e21e 252
5d9f8747
IK
253Whatever is on the left side of the arrow, whether a reference or a
254class name, is passed to the method subroutine as its first argument.
255So the above code is mostly equivalent to:
a0d0e21e 256
5d9f8747
IK
257 my $fred = Critter::find("Critter", "Fred");
258 Critter::display($fred, "Height", "Weight");
a0d0e21e 259
5d9f8747
IK
260How does Perl know which package the subroutine is in? By looking at
261the left side of the arrow, which must be either a package name or a
262reference to an object, i.e. something that has been blessed to a
5f7b1de2 263package. Either way, that's the package where Perl starts looking. If
5d9f8747
IK
264that package has no subroutine with that name, Perl starts looking for
265it in any base classes of that package, and so on.
a0d0e21e 266
5f7b1de2 267If you need to, you I<can> force Perl to start looking in some other package:
a0d0e21e 268
5d9f8747
IK
269 my $barney = MyCritter->Critter::find("Barney");
270 $barney->Critter::display("Height", "Weight");
a0d0e21e 271
5d9f8747
IK
272Here C<MyCritter> is presumably a subclass of C<Critter> that defines
273its own versions of find() and display(). We haven't specified what
274those methods do, but that doesn't matter above since we've forced Perl
275to start looking for the subroutines in C<Critter>.
a0d0e21e 276
5d9f8747 277As a special case of the above, you may use the C<SUPER> pseudo-class to
5f7b1de2
JH
278tell Perl to start looking for the method in the packages named in the
279current class's C<@ISA> list.
d74e8afc 280X<SUPER>
a0d0e21e 281
5d9f8747
IK
282 package MyCritter;
283 use base 'Critter'; # sets @MyCritter::ISA = ('Critter');
a0d0e21e 284
5d9f8747
IK
285 sub display {
286 my ($self, @args) = @_;
287 $self->SUPER::display("Name", @args);
288 }
a0d0e21e 289
50506ccd
DM
290It is important to note that C<SUPER> refers to the superclass(es) of the
291I<current package> and not to the superclass(es) of the object. Also, the
029f3b44
DM
292C<SUPER> pseudo-class can only currently be used as a modifier to a method
293name, but not in any of the other ways that class names are normally used,
294eg:
d74e8afc 295X<SUPER>
029f3b44
DM
296
297 something->SUPER::method(...); # OK
298 SUPER::method(...); # WRONG
299 SUPER->method(...); # WRONG
300
5d9f8747
IK
301Instead of a class name or an object reference, you can also use any
302expression that returns either of those on the left side of the arrow.
303So the following statement is valid:
a0d0e21e 304
5d9f8747 305 Critter->find("Fred")->display("Height", "Weight");
a0d0e21e 306
5f7b1de2 307and so is the following:
cb1a09d0 308
5d9f8747 309 my $fred = (reverse "rettirC")->find(reverse "derF");
cb1a09d0 310
d9693f5a
SP
311The right side of the arrow typically is the method name, but a simple
312scalar variable containing either the method name or a subroutine
313reference can also be used.
314
5d9f8747 315=head2 Indirect Object Syntax
d74e8afc 316X<indirect object syntax> X<invocation, indirect> X<indirect>
cb1a09d0 317
5f7b1de2
JH
318The other way to invoke a method is by using the so-called "indirect
319object" notation. This syntax was available in Perl 4 long before
320objects were introduced, and is still used with filehandles like this:
748a9306 321
5d9f8747 322 print STDERR "help!!!\n";
19799a22 323
5d9f8747 324The same syntax can be used to call either object or class methods.
19799a22 325
5d9f8747
IK
326 my $fred = find Critter "Fred";
327 display $fred "Height", "Weight";
19799a22 328
5d9f8747
IK
329Notice that there is no comma between the object or class name and the
330parameters. This is how Perl can tell you want an indirect method call
331instead of an ordinary subroutine call.
19799a22 332
5d9f8747 333But what if there are no arguments? In that case, Perl must guess what
5f7b1de2
JH
334you want. Even worse, it must make that guess I<at compile time>.
335Usually Perl gets it right, but when it doesn't you get a function
336call compiled as a method, or vice versa. This can introduce subtle bugs
337that are hard to detect.
5d9f8747 338
5f7b1de2
JH
339For example, a call to a method C<new> in indirect notation -- as C++
340programmers are wont to make -- can be miscompiled into a subroutine
5d9f8747
IK
341call if there's already a C<new> function in scope. You'd end up
342calling the current package's C<new> as a subroutine, rather than the
343desired class's method. The compiler tries to cheat by remembering
5f7b1de2
JH
344bareword C<require>s, but the grief when it messes up just isn't worth the
345years of debugging it will take you to track down such subtle bugs.
5d9f8747
IK
346
347There is another problem with this syntax: the indirect object is
348limited to a name, a scalar variable, or a block, because it would have
349to do too much lookahead otherwise, just like any other postfix
350dereference in the language. (These are the same quirky rules as are
351used for the filehandle slot in functions like C<print> and C<printf>.)
352This can lead to horribly confusing precedence problems, as in these
353next two lines:
19799a22
GS
354
355 move $obj->{FIELD}; # probably wrong!
356 move $ary[$i]; # probably wrong!
357
358Those actually parse as the very surprising:
359
360 $obj->move->{FIELD}; # Well, lookee here
4f298f32 361 $ary->move([$i]); # Didn't expect this one, eh?
19799a22
GS
362
363Rather than what you might have expected:
364
365 $obj->{FIELD}->move(); # You should be so lucky.
366 $ary[$i]->move; # Yeah, sure.
367
5d9f8747
IK
368To get the correct behavior with indirect object syntax, you would have
369to use a block around the indirect object:
19799a22 370
5d9f8747
IK
371 move {$obj->{FIELD}};
372 move {$ary[$i]};
373
374Even then, you still have the same potential problem if there happens to
375be a function named C<move> in the current package. B<The C<< -> >>
376notation suffers from neither of these disturbing ambiguities, so we
377recommend you use it exclusively.> However, you may still end up having
378to read code using the indirect object notation, so it's important to be
379familiar with it.
748a9306 380
a2bdc9a5 381=head2 Default UNIVERSAL methods
d74e8afc 382X<UNIVERSAL>
a2bdc9a5
PP
383
384The C<UNIVERSAL> package automatically contains the following methods that
385are inherited by all other classes:
386
387=over 4
388
71be2cbc 389=item isa(CLASS)
d74e8afc 390X<isa>
a2bdc9a5 391
68dc0745 392C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
a2bdc9a5 393
da279afe 394You can also call C<UNIVERSAL::isa> as a subroutine with two arguments. Of
395course, this will do the wrong thing if someone has overridden C<isa> in a
396class, so don't do it.
a2bdc9a5 397
da279afe 398If you need to determine whether you've received a valid invocant, use the
399C<blessed> function from L<Scalar::Util>:
d74e8afc 400X<invocant> X<blessed>
a2bdc9a5 401
da279afe 402 if (blessed($ref) && $ref->isa( 'Some::Class')) {
403 # ...
404 }
3189d65a 405
da279afe 406C<blessed> returns the name of the package the argument has been
407blessed into, or C<undef>.
3189d65a 408
71be2cbc 409=item can(METHOD)
d74e8afc 410X<can>
a2bdc9a5
PP
411
412C<can> checks to see if its object has a method called C<METHOD>,
413if it does then a reference to the sub is returned, if it does not then
414I<undef> is returned.
415
da279afe 416C<UNIVERSAL::can> can also be called as a subroutine with two arguments. It'll
417always return I<undef> if its first argument isn't an object or a class name.
418The same caveats for calling C<UNIVERSAL::isa> directly apply here, too.
b32b0a5d 419
71be2cbc 420=item VERSION( [NEED] )
d74e8afc 421X<VERSION>
760ac839 422
71be2cbc
PP
423C<VERSION> returns the version number of the class (package). If the
424NEED argument is given then it will check that the current version (as
425defined by the $VERSION variable in the given package) not less than
426NEED; it will die if this is not the case. This method is normally
427called as a class method. This method is called automatically by the
428C<VERSION> form of C<use>.
a2bdc9a5 429
a2bdc9a5 430 use A 1.2 qw(some imported subs);
71be2cbc
PP
431 # implies:
432 A->VERSION(1.2);
a2bdc9a5 433
a2bdc9a5
PP
434=back
435
436B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
437C<isa> uses a very similar method and cache-ing strategy. This may cause
438strange effects if the Perl code dynamically changes @ISA in any package.
439
440You may add other methods to the UNIVERSAL class via Perl or XS code.
14218588 441You do not need to C<use UNIVERSAL> to make these methods
38242c00 442available to your program (and you should not do so).
a2bdc9a5 443
54310121 444=head2 Destructors
d74e8afc 445X<destructor> X<DESTROY>
a0d0e21e
LW
446
447When the last reference to an object goes away, the object is
448automatically destroyed. (This may even be after you exit, if you've
449stored references in global variables.) If you want to capture control
450just before the object is freed, you may define a DESTROY method in
451your class. It will automatically be called at the appropriate moment,
4e8e7886
GS
452and you can do any extra cleanup you need to do. Perl passes a reference
453to the object under destruction as the first (and only) argument. Beware
454that the reference is a read-only value, and cannot be modified by
455manipulating C<$_[0]> within the destructor. The object itself (i.e.
456the thingy the reference points to, namely C<${$_[0]}>, C<@{$_[0]}>,
457C<%{$_[0]}> etc.) is not similarly constrained.
458
459If you arrange to re-bless the reference before the destructor returns,
460perl will again call the DESTROY method for the re-blessed object after
461the current one returns. This can be used for clean delegation of
462object destruction, or for ensuring that destructors in the base classes
463of your choosing get called. Explicitly calling DESTROY is also possible,
464but is usually never needed.
465
14218588 466Do not confuse the previous discussion with how objects I<CONTAINED> in the current
4e8e7886
GS
467one are destroyed. Such objects will be freed and destroyed automatically
468when the current object is freed, provided no other references to them exist
469elsewhere.
a0d0e21e
LW
470
471=head2 Summary
472
5f05dabc 473That's about all there is to it. Now you need just to go off and buy a
a0d0e21e
LW
474book about object-oriented design methodology, and bang your forehead
475with it for the next six months or so.
476
cb1a09d0 477=head2 Two-Phased Garbage Collection
d74e8afc
ITB
478X<garbage collection> X<GC> X<circular reference>
479X<reference, circular> X<DESTROY> X<destructor>
cb1a09d0 480
14218588
GS
481For most purposes, Perl uses a fast and simple, reference-based
482garbage collection system. That means there's an extra
cb1a09d0
AD
483dereference going on at some level, so if you haven't built
484your Perl executable using your C compiler's C<-O> flag, performance
485will suffer. If you I<have> built Perl with C<cc -O>, then this
486probably won't matter.
487
488A more serious concern is that unreachable memory with a non-zero
489reference count will not normally get freed. Therefore, this is a bad
54310121 490idea:
cb1a09d0
AD
491
492 {
493 my $a;
494 $a = \$a;
54310121 495 }
cb1a09d0
AD
496
497Even thought $a I<should> go away, it can't. When building recursive data
498structures, you'll have to break the self-reference yourself explicitly
499if you don't care to leak. For example, here's a self-referential
500node such as one might use in a sophisticated tree structure:
501
502 sub new_node {
eac7fe86
O
503 my $class = shift;
504 my $node = {};
cb1a09d0
AD
505 $node->{LEFT} = $node->{RIGHT} = $node;
506 $node->{DATA} = [ @_ ];
507 return bless $node => $class;
54310121 508 }
cb1a09d0
AD
509
510If you create nodes like that, they (currently) won't go away unless you
511break their self reference yourself. (In other words, this is not to be
512construed as a feature, and you shouldn't depend on it.)
513
514Almost.
515
516When an interpreter thread finally shuts down (usually when your program
517exits), then a rather costly but complete mark-and-sweep style of garbage
518collection is performed, and everything allocated by that thread gets
519destroyed. This is essential to support Perl as an embedded or a
54310121 520multithreadable language. For example, this program demonstrates Perl's
cb1a09d0
AD
521two-phased garbage collection:
522
54310121 523 #!/usr/bin/perl
cb1a09d0
AD
524 package Subtle;
525
526 sub new {
527 my $test;
528 $test = \$test;
529 warn "CREATING " . \$test;
530 return bless \$test;
54310121 531 }
cb1a09d0
AD
532
533 sub DESTROY {
534 my $self = shift;
535 warn "DESTROYING $self";
54310121 536 }
cb1a09d0
AD
537
538 package main;
539
540 warn "starting program";
541 {
542 my $a = Subtle->new;
543 my $b = Subtle->new;
544 $$a = 0; # break selfref
545 warn "leaving block";
54310121 546 }
cb1a09d0
AD
547
548 warn "just exited block";
549 warn "time to die...";
550 exit;
551
2359510d
SD
552When run as F</foo/test>, the following output is produced:
553
554 starting program at /foo/test line 18.
555 CREATING SCALAR(0x8e5b8) at /foo/test line 7.
556 CREATING SCALAR(0x8e57c) at /foo/test line 7.
557 leaving block at /foo/test line 23.
558 DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13.
559 just exited block at /foo/test line 26.
560 time to die... at /foo/test line 27.
cb1a09d0
AD
561 DESTROYING Subtle=SCALAR(0x8e57c) during global destruction.
562
563Notice that "global destruction" bit there? That's the thread
54310121 564garbage collector reaching the unreachable.
cb1a09d0 565
14218588
GS
566Objects are always destructed, even when regular refs aren't. Objects
567are destructed in a separate pass before ordinary refs just to
cb1a09d0 568prevent object destructors from using refs that have been themselves
5f05dabc 569destructed. Plain refs are only garbage-collected if the destruct level
cb1a09d0
AD
570is greater than 0. You can test the higher levels of global destruction
571by setting the PERL_DESTRUCT_LEVEL environment variable, presuming
572C<-DDEBUGGING> was enabled during perl build time.
64cea5fd 573See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
cb1a09d0
AD
574
575A more complete garbage collection strategy will be implemented
576at a future date.
577
5a964f20
TC
578In the meantime, the best solution is to create a non-recursive container
579class that holds a pointer to the self-referential data structure.
580Define a DESTROY method for the containing object's class that manually
581breaks the circularities in the self-referential structure.
582
a0d0e21e
LW
583=head1 SEE ALSO
584
8257a158 585A kinder, gentler tutorial on object-oriented programming in Perl can
890a53b9 586be found in L<perltoot>, L<perlboot> and L<perltooc>. You should
8257a158
MS
587also check out L<perlbot> for other object tricks, traps, and tips, as
588well as L<perlmodlib> for some style guides on constructing both
589modules and classes.