This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Remove all references to old OO tutorial docs, and add refs to perlootut where approp...
[perl5.git] / pod / perlootut.pod
CommitLineData
dbfe2941
DR
1=encoding utf8
2
3=for comment
4Consistent formatting of this file is achieved with:
5 perl ./Porting/podtidy pod/perlootut.pod
6
7=head1 NAME
8
9perlootut - Object-Oriented Programming in Perl Tutorial
10
11=head1 DATE
12
13This document was created in February, 2011.
14
15=head1 DESCRIPTION
16
17This document provides an introduction to object-oriented programming
18in Perl. It begins with a brief overview of the concepts behind object
19oriented design. Then it introduces several different OO systems from
20L<CPAN|http://search.cpan.org> which build on top of what Perl
21provides.
22
23By default, Perl's built-in OO system is very minimal, leaving you to
24do most of the work. This minimalism made a lot of sense in 1994, but
25in the years since Perl 5.0 we've seen a number of common patterns
26emerge in Perl OO. Fortunately, Perl's flexibility has allowed a rich
27ecosystem of Perl OO systems to flourish.
28
29If you want to know how Perl OO works under the hood, the L<perlobj>
30document explains the nitty gritty details.
31
32This document assumes that you already understand the basics of Perl
33syntax, variable types, operators, and subroutine calls. If you don't
34understand these concepts yet, please read L<perlintro> first. You
35should also read the L<perlsyn>, L<perlop>, and L<perlsub> documents.
36
37=head1 OBJECT-ORIENTED FUNDAMENTALS
38
39Most object systems share a number of common concepts. You've probably
40heard terms like "class", "object, "method", and "attribute" before.
41Understanding the concepts will make it much easier to read and write
42object-oriented code. If you're already familiar with these terms, you
43should still skim this section, since it explains each concept in terms
44of Perl's OO implementation.
45
46Perl's OO system is class-based. Class-based OO is fairly common. It's
47used by Java, C++, C#, Python, Ruby, and many other languages. There
48are other object orientation paradigms as well. JavaScript is the most
49popular language to use another paradigm. JavaScript's OO system is
50prototype-based.
51
52=head2 Object
53
54An B<object> is a data structure that bundles together data and
55subroutines which operate on that data. An object's data is called
56B<attributes>, and its subroutines are called B<methods>. An object can
57be thought of as a noun (a person, a web service, a computer).
58
d49ecf98
DR
59An object represents a single discrete thing. For example, an object
60might represent a person. The attributes for a person object might
61include name, birth date, and country of residence. If we created an
62object to represent Larry Wall, Perl's creator, that object's name
dbfe2941
DR
63would be "Larry Wall", born on "September 27, 1954", and living in
64"USA".
65
66The methods associated with a person might include C<print_greeting()>
67and C<calculate_age()>.
68
69In Perl most objects are hash references, but the OO systems we
70recommend keep you from having to worry about this. In practice, it's
71best to consider an object's internal data structure opaque.
72
73=head2 Class
74
75A B<class> defines the behavior of a category of objects. A class is a
76name for a category (like "Person"), and a class also defines the
77behavior of objects in that category.
78
79All objects belong to a specific class. For example, our Larry Wall
80object belongs to the C<Person> class. When we want to create a
81specific object, we start with its class, and B<construct> or
82B<instantiate> an object. A specific object is often referred to as an
83B<instance> of a class.
84
85In Perl, any package can be a class. The difference between a package
86which is a class and one which isn't is based on how the package is
87used. Here's our "class declaration" for the Person class:
88
89 package Person;
90
91In Perl, there is no special keyword for constructing an object.
92However, most OO modules on CPAN use a method named C<new()> to
93construct a new object:
94
95 my $larry = Person->new(
96 name => 'Larry Wall',
97 birth_date => '1954-09-27',
98 country_code => 'us',
99 );
100
101(Don't worry about that C<< -> >> operator, it will be explained
102later.)
103
104=head3 Blessing
105
106As we said earlier, most Perl objects are hash references, but an
107object can be a reference to any Perl data type (scalar, array, etc.).
108Turning a plain reference into an object is done by B<blessing> that
109reference using Perl's C<bless> function.
110
111While we strongly suggest you don't build your objects from scratch,
112you should know the term B<bless>. A B<blessed> reference is an object.
113We sometimes say that an object has been "blessed into a class".
114
115Once a reference has been blessed, the C<blessed> function from the
116L<Scalar::Util> core module can tell us its class name. This subroutine
117returns an object's class when passed an object, and false otherwise.
118
119 use Scalar::Util 'blessed';
120
121 print blessed($hash); # undef
122 print blessed($larry); # Person
123
124=head3 Constructor
125
126A B<constructor> creates a new object. In Perl, a class's constructor
127is just another method, unlike some other languages, which provide
128syntax for constructors. Most Perl classes use C<new> as the name for
129their constructor:
130
131 my $file = File->new();
132
133=head2 Methods
134
135You already learned that a B<method> is a subroutine that operates on
136an object's data. You can think of a method as the things that an
137object can I<do>.
138
139In Perl, methods are simply subroutines that live in a class's package.
140Methods are always written to receive the object as their first
141argument:
142
143 sub print_greeting {
144 my $self = shift;
145
146 print "Hello, ", $self->name, "\n";
147 }
148
149 $larry->print_greeting; # Hello, Larry Wall
150
151What makes a method special is I<how it's called>. The arrow operator
152(C<< -> >>) tells Perl that we are calling a method.
153
154When we make a method call, Perl arranges for the method's B<invocant>
155to be passed as the first argument. B<Invocant> is a fancy name for the
156thing on the left side of the arrow. The invocant can either be a class
157name or an object. We can also pass additional arguments to the method:
158
159 sub print_greeting {
160 my $self = shift;
161 my $greeting = shift // "Hello";
162
163 print $greeting, ", ", $self->name, "\n";
164 }
165
166 $larry->print_greeting("Yo, Wassup"); # Yo, Wassup, Larry Wall
167
168=head2 Attributes
169
170Each class can define its B<attributes>. When we instantiate an object,
171we assign values to those attributes. For example, every C<Person>
172object has a name. Attributes are sometimes called B<properties>.
173
174Perl has no special syntax for attributes. Under the hood, attributes
175are often stored as keys in the object's hash reference, but don't
176worry about this.
177
178We recommend that you only access attributes via B<accessor> methods.
179These are methods that can get or set the value of each attribute. We
180saw this earlier in the C<print_greeting()> example, which calls C<<
181$self->name >>.
182
183You might also see the terms B<getter> and B<setter>. These are two
184types of accessors. A getter gets the attribute's value, while a setter
185sets it.
186
187Attributes are typically defined as read-only or read-write. Read-only
188attributes can only be set when the object is first created, while
189read-write attributes can be altered at any time.
190
191The value of an attribute may itself be another object. For example,
192instead of returning its birth date as a string, the C<Person> class
193could return a L<DateTime> object representing that date.
194
195It's possible to have a class that does not expose any publicly
196settable attributes. Not every class has attributes and methods.
197
198=head2 Polymorphism
199
200B<Polymorphism> is a fancy way of saying that objects from two
201different classes share an API. For example, we could have C<Person>
202and C<Animal> classes which both have a C<speak()> method. This method
203might produce different output for each class, but the basic API is the
204same.
205
206While the two classes may differ in many ways, when it comes to the
207C<speak()> method, they are the same. This means that we can try to
208call the C<speak()> method on an object of either class, and B<we don't
209have to know what class the object belongs to!>
210
211Polymorphism is one of the key concepts of object-oriented design.
212
213=head2 Inheritance
214
215B<Inheritance> is a way to specialize an existing class. It allows one
216class to reuse the methods and attributes of another class.
217
218We often refer to inheritance relationships as B<parent-child> or
d49ecf98
DR
219C<superclass/subclass> relationships. Sometimes we say that the child
220has an B<is-a> relationship with its parent class.
dbfe2941
DR
221
222Inheritance is best used to create a specialized version of a class.
223For example, we could create an C<Employee> class which B<inherits>
224from C<Person>. An C<Employee> B<is-a> I<more specific> type of
225C<Person>. All employees are persons, but not all persons are
226employees.
227
228C<Person> is a B<superclass> of C<Employee>, and C<Employee> is a
229B<subclass> of C<Person>.
230
231 package Employee;
232
233 use parent 'Person';
234
235The L<parent> module is one of several ways that Perl lets you define
236inheritance relationships.
237
238Perl allows multiple inheritance, which means that a class can inherit
239from multiple parents. While this is possible, we strongly recommend
240against it. Generally, you can use B<roles> to do everything you can do
241with multiple inheritance in a cleaner way.
242
243Note that there's nothing wrong with defining multiple subclasses of a
244given class. This is both common and safe. For example, we might define
245C<Employee::Permanent> and C<Employee::Temporary> classes to
246distinguish between different types of employees.
247
248=head3 Overriding methods and method resolution
249
250Inheritance allows two classes to share code. By default, every method
251in the parent class is also available in the child. The child can
252explicitly B<override> a parent's method to provide its own
253implementation. For example, if we have an C<Employee> object, it has
d49ecf98 254the C<print_greeting()> method from C<Person>:
dbfe2941
DR
255
256 my $larry = Employee->new(
257 name => 'Larry Wall',
258 birth_date => '1954-09-27',
259 country_code => 'us',
260 job_title => 'Hacker Extraordinaire',
261 );
262
263 $larry->print_greeting; # Hello, Larry Wall
264
265If we wanted to include the employee's job title in the greeting, we
266could override the method:
267
268 package Employee;
269
270 use parent 'Person';
271
272 sub print_greeting {
273 my $self = shift;
274
275 print "Hello, ", $self->name, " - ", $self->job_title, "\n";
276 }
277
278 $larry->print_greeting; # Hello, Larry Wall - Hacker Extraordinaire
279
280The process of determining what method should be used is called
281B<method resolution>. What Perl does is look at the object's class
282first (C<Employee> in this case). If that class defines the method,
283then that class's version of the method is called. If not, Perl looks
284at each parent class in turn. For C<Employee>, its only parent is
285C<Person>. If C<Employee> does not define the method, but C<Person>
286does, then Perl calls the method in C<Person>.
287
288If C<Person> inherited from C<Animal>, which inherited from C<Thing>,
289then Perl would keep looking "up the chain" if necessary.
290
291It is possible to explicitly call a parent method from a child:
292
293 package Employee;
294
295 use parent 'Person';
296
297 sub print_greeting {
298 my $self = shift;
299
300 $self->SUPER::print_greeting();
301
302 print "Your job is ", $self->job_title, "\n";
303 }
304
305The C<SUPER::> bit tells Perl to look for the C<print_greeting()> in
306the C<Employee> class's inheritance chain. When it finds the parent
307class that implements this method, the method is called.
308
309We mentioned multiple inheritance earlier. The main problem with
310multiple inheritance is that it greatly complicates method resolution.
311See L<perlobj> for more details.
312
313=head2 Encapsulation
314
315B<Encapsulation> is the idea that an object is opaque. When another
316developer uses your class, they don't need to know I<how> it is
317implemented, they just need to know I<what> it does.
318
319Encapsulation is important for several reasons. First, it allows you to
320separate the public API from the private implementation. This means you
321can change that implementation without breaking the API.
322
323Second, when classes are well encapsulated, they become easier to
324subclass. Ideally, a subclass uses the same APIs to access object data
325that its parent class uses. In reality, subclassing sometimes involves
326violating encapsulation, but a good API can minimize the need to do
327this.
328
329We mentioned earlier that most Perl objects are implemented as hash
330references under the hood. The principle of encapsulation tells us that
331we should not rely on this. Instead, we should use accessor methods to
332access the data in that hash reference. The object systems that we
333recommend below all automate the generation of accessor methods. If you
334use one of them, you should never have to access the object as a hash
335reference directly.
336
337=head2 Composition
338
339In object-oriented code, we often find that one object references
340another object. This is called B<composition>, or a B<has-a>
341relationship.
342
343Earlier, we mentioned that the C<Person> class's C<birth_date> accessor
344could return a L<DateTime> object. This is a perfect example of
d49ecf98
DR
345composition. We could go even further, and make the C<name> and
346C<country> accessors return objects as well. The C<Person> class would
347then be B<composed> of several other objects.
dbfe2941
DR
348
349=head2 Roles
350
351B<Roles> are something that a class I<does>, rather than something that
352it I<is>. Roles are relatively new to Perl, but have become rather
353popular. Roles are B<applied> to classes. Sometimes we say that classes
354B<consume> roles.
355
356Roles are an alternative to inheritance for providing polymorphism.
357Let's assume we have two classes, C<Radio> and C<Computer>. Both of
358these things have on/off switches. We want to model that in our class
359definitions.
360
361We could have both classes inherit from a common parent, like
362C<Machine>, but not all machines have on/off switches. We could create
363a parent class called C<HasOnOffSwitch>, but that is very artificial.
364Radios and computers are not specializations of this parent. This
365parent is really a rather ridiculous creation.
366
367This is where roles come in. It makes a lot of sense to create a
368C<HasOnOffSwitch> role and apply it to both classes. This role would
369define a known API like providing C<turn_on()> and C<turn_off()>
370methods.
371
372Perl does not have any built-in way to express roles. In the past,
373people just bit the bullet and used multiple inheritance. Nowadays,
374there are several good choices on CPAN for using roles.
375
ce843b44
DR
376=head2 When to Use OO
377
378Object Orientation is not the best solution to every problem. In I<Perl
379Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
380Damian Conway provides a list of criteria to use when deciding if OO is
381the right fit for your problem:
382
383=over 4
384
385=item
386
387The system being designed is large, or is likely to become large.
388
389=item
390
391The data can be aggregated into obvious structures, especially if
392there's a large amount of data in each aggregate.
393
394=item
395
396The various types of data aggregate form a natural hierarchy that
397facilitates the use of inheritance and polymorphism.
398
399=item
400
401You have a piece of data on which many different operations are
402applied.
403
404=item
405
406You need to perform the same general operations on related types of
407data, but with slight variations depending on the specific type of data
408the operations are applied to.
409
410=item
411
412It's likely you'll have to add new data types later.
413
414=item
415
416The typical interactions between pieces of data are best represented by
417operators.
418
419=item
420
421The implementation of individual components of the system is likely to
422change over time.
423
424=item
425
426The system design is already object-oriented.
427
428=item
429
430Large numbers of other programmers will be using your code modules.
431
432=back
433
dbfe2941
DR
434=head1 PERL OO SYSTEMS
435
436As we mentioned before, Perl's built-in OO system is very minimal, but
437also quite flexible. Over the years, many people have developed systems
438which build on top of Perl's built-in system to provide more features
439and convenience.
440
441We strongly recommend that you use one of these systems. Even the most
442minimal of them eliminates a lot of repetitive boilerplate. There's
443really no good reason to write your classes from scratch in Perl.
444
445If you are interested in the guts underlying these systems, check out
446L<perlobj>.
447
448=head2 Moose
449
450L<Moose> bills itself as a "postmodern object system for Perl 5". Don't
451be scared, the "postmodern" label is a callback to Larry's description
452of Perl as "the first postmodern computer language".
453
454C<Moose> provides a complete, modern OO system. Its biggest influence
455is the Common Lisp Object System, but it also borrows ideas from
456Smalltalk and several other languages. C<Moose> was created by Stevan
457Little, and draws heavily from his work on the Perl 6 OO design.
458
459C<Moose> provides a number of features:
460
461=over 4
462
463=item * Declarative sugar
464
465C<Moose> provides a layer of declarative "sugar" for defining classes.
466That sugar is just a set of exported functions that make declaring how
467your class works simpler and more palatable. This lets you describe
468I<what> your class is, rather than having to tell Perl I<how> to
469implement your class.
470
471Here's a simple but complete C<Moose> class:
472
473 package Person;
474 use Moose;
475
476 has name => ( is => 'ro' );
477 has birth_date => ( is => 'ro' );
478 has country_code => ( is => 'ro' );
479
480 sub print_greeting {
481 my $self = shift;
482
483 print "Hello, ", $self->name, "\n";
484 }
485
486The C<has()> subroutine declares an attribute, and C<Moose>
487automatically creates accessors for these attributes. It also takes
488care of creating a C<new()> method for you. This constructor knows
489about the attributes you declared, so you can set them when creating a
490new C<Person>.
491
492=item * Roles built-in
493
494C<Moose> lets you define roles the same way you define classes:
495
496 package HasOnOfSwitch;
497 use Moose::Role;
498
499 has is_on => (
500 is => 'rw',
501 isa => 'Bool',
502 );
503
504 sub turn_on {
505 my $self = shift;
506 $self->is_on(1);
507 }
508
509 sub turn_off {
510 my $self = shift;
511 $self->is_on(0);
512 }
513
514=item * A miniature type system
515
516In the example above, you can see that we passed C<< isa => 'Bool' >>
517to C<has()> when creating our C<is_on> attribute. This tells C<Moose>
518that this attribute must be a boolean value. If we try to set it to an
519invalid value, our code will throw an error.
520
521=item * Full introspection and manipulation
522
523Perl's built-in introspection features are fairly minimal. C<Moose>
524builds on top of them and creates a full introspection layer for your
525classes. This lets you ask questions like "what methods does the Person
526class implement?" It also lets you modify your classes
527programmatically.
528
529=item * Self-hosted and extensible
530
531C<Moose> describes itself using its own introspection API. Besides
532being a cool trick, this means that you can extend C<Moose> using
533C<Moose> itself.
534
535=item * Rich ecosystem
536
537There is a rich ecosystem of C<Moose> extensions on CPAN under the
538L<MooseX|http://search.cpan.org/search?query=MooseX&mode=dist>
539namespace. In addition, many modules on CPAN already use C<Moose>,
540providing you with lots of examples to learn from.
541
542=item * Many more features
543
544C<Moose> is a very powerful tool, and we can't cover all of its
545features here. We encourage you to learn more by reading the C<Moose>
546documentation, starting with
547L<Moose::Manual|http://search.cpan.org/perldoc?Moose::Manual>.
548
549=back
550
551Of course, C<Moose> isn't perfect.
552
553C<Moose> can make your code slower to load. C<Moose> itself is not
554small, and it does a I<lot> of code generation when you define your
555class. This code generation means that your runtime code is as fast as
556it can be, but you pay for this when your modules are first loaded.
557
558This load time hit can be a problem when startup speed is important,
559such as with a command-line script or a "plain vanilla" CGI script that
560must be loaded each time it is executed.
561
562Before you panic, know that many people do use C<Moose> for
563command-line tools and other startup-sensitive code. We encourage you
564to try C<Moose> out first before worrying about startup speed.
565
566C<Moose> also has several dependencies on other modules. Most of these
567are small stand-alone modules, a number of which have been spun off
568from C<Moose>. C<Moose> itself, and some of its dependencies, require a
569compiler. If you need to install your software on a system without a
570compiler, or if having I<any> dependencies is a problem, then C<Moose>
571may not be right for you.
572
573=head3 Mouse
574
575If you try C<Moose> and find that one of these issues is preventing you
576from using C<Moose>, we encourage you to consider L<Mouse> next.
577C<Mouse> implements a subset of C<Moose>'s functionality in a simpler
578package. For all features that it does implement, the end-user API is
579I<identical> to C<Moose>, meaning you can switch from C<Mouse> to
580C<Moose> quite easily.
581
582C<Mouse> does not implement most of C<Moose>'s introspection API, so
583it's often faster when loading your modules. Additionally, it has no
584I<required> non-core dependencies and can run without a compiler. If
585you do have a compiler, C<Mouse> will use it to compile some of its
586code for a speed boost.
587
588Finally, it ships with a C<C<Mouse>::Tiny> module that takes most of
589C<Mouse>'s features and bundles them up in a single module file. You
590can copy this module file into your application's library directory for
591easy bundling.
592
593The C<Moose> authors hope that one day C<Mouse> can be made obsolete by
594improving C<Moose> enough, but for now it provides a worthwhile
595alternative to C<Moose>.
596
597=head2 Class::Accessor
598
599L<Class::Accessor> is the polar opposite of C<Moose>. It provides very
600few features, nor is it self-hosting.
601
602It is, however, very simple, pure Perl, and it has no non-core
603dependencies. It also provides a "Moose-like" API on demand for the
604features it supports.
605
606Even though it doesn't do much, it is still preferable to writing your
607own classes from scratch.
608
609Here's our C<Person> class with C<Class::Accessor>:
610
611 package Person;
612 use Class::Accessor 'antlers';
613
614 has name => ( is => 'ro' );
615 has birth_date => ( is => 'ro' );
616 has country_code => ( is => 'ro' );
617
618 sub print_greeting {
619 my $self = shift;
620
621 print "Hello, ", $self->name, "\n";
622 }
623
624The C<antlers> import flag tells C<Class::Accessor> that you want to
625define your attributes using C<Moose>-like syntax. The only parameter
626that you can pass to C<has> is C<is>. We recommend that you use this
627Moose-like syntax if you choose C<Class::Accessor> since it means you
628will have a smoother upgrade path if you later decide to move to
629C<Moose>.
630
631Like C<Moose>, C<Class::Accessor> generates accessor methods and a
632constructor for your class.
633
634=head2 Object::Tiny
635
636Finally, we have L<Object::Tiny>. This module truly lives up to its
637name. It has an incredibly minimal API and absolutely no dependencies
638(core or not). Still, we think it's a lot easier to use than writing
639your own OO code from scratch.
640
641Here's our C<Person> class once more:
642
643 package Person;
644 use Object::Tiny qw( name birth_date country_code );
645
646 sub print_greeting {
647 my $self = shift;
648
649 print "Hello, ", $self->name, "\n";
650 }
651
652That's it!
653
654With C<Object::Tiny>, all accessors are read-only. It generates a
655constructor for you, as well as the accessors you define.
656
657=head2 Role::Tiny
658
659As we mentioned before, roles provide an alternative to inheritance,
660but Perl does not have any built-in role support. If you choose to use
661Moose, it comes with a full-fledged role implementation. However, if
662you use one of our other recommended OO modules, you can still use
663roles with L<Role::Tiny>
664
665C<Role::Tiny> provides some of the same features as Moose's role
666system, but in a much smaller package. Most notably, it doesn't support
667any sort of attribute declaration, so you have to do that by hand.
668Still, it's useful, and works well with C<Class::Accessor> and
669C<Object::Tiny>
670
671=head2 OO System Summary
672
673Here's a brief recap of the options we covered:
674
675=over 4
676
677=item * L<Moose>
678
679C<Moose> is the maximal option. It has a lot of features, a big
680ecosystem, and a thriving user base. We also covered L<Mouse> briefly.
681C<Mouse> is C<Moose> lite, and a reasonable alternative when Moose
682doesn't work for your application.
683
684=item * L<Class::Accessor>
685
686C<Class::Accessor> does a lot less than C<Moose>, and is a nice
687alternative if you find C<Moose> overwhelming. It's been around a long
688time and is well battle-tested. It also has a minimal C<Moose>
689compatibility mode which makes moving from C<Class::Accessor> to
690C<Moose> easy.
691
692=item * L<Object::Tiny>
693
694C<Object::Tiny> is the absolute minimal option. It has no dependencies,
695and almost no syntax to learn. It's a good option for a super minimal
696environment and for throwing something together quickly without having
697to worry about details.
698
699=item * L<Role::Tiny>
700
701Use C<Role::Tiny> with C<Class::Accessor> or C<Object::Tiny> if you
702find yourself considering multiple inheritance. If you go with
703C<Moose>, it comes with its own role implementation.
704
705=back
706
707=head2 Other OO Systems
708
709There are literally dozens of other OO-related modules on CPAN besides
710those covered here, and you're likely to run across one or more of them
711if you work with other people's code.
712
713In addition, plenty of code in the wild does all of its OO "by hand",
714using just the Perl built-in OO features. If you need to maintain such
715code, you should read L<perlobj> to understand exactly how Perl's
716built-in OO works.
717
718=head1 CONCLUSION
719
720As we said before, Perl's minimal OO system has lead to a flourishing
721of OO systems on CPAN. While you can still drop down to the bare metal
722and write your classes by hand, there's really no reason to do that in
7232011.
724
725For small systems, L<Object::Tiny> and L<Class::Accessor> both provide
726minimal object systems that take care of basic boilerplate for you.
727
728For bigger projects, L<Moose> provides a rich set of features that will
729let you focus on implementing your business logic.
730
731We encourage you to play with and evaluate L<Moose>,
732L<Class::Accessor>, and L<Object::Tiny> to see which OO system is right
733for you.
734
735=cut