This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
New perldelta for 5.27.6
[perl5.git] / pod / perlobj.pod
index 015b1c9..d5d242f 100644 (file)
@@ -131,7 +131,7 @@ documented methods on the object.
 Note, however, that (unlike most other OO languages) Perl does not
 ensure or enforce encapsulation in any way. If you want objects to
 actually I<be> opaque you need to arrange for that yourself. This can
-be done in a varierty of ways, including using L<"Inside-Out objects">
+be done in a variety of ways, including using L</"Inside-Out objects">
 or modules from CPAN.
 
 =head3 Objects Are Blessed; Variables Are Not
@@ -148,10 +148,10 @@ demonstrated with this code:
   my $bar = $foo;
 
   bless $foo, 'Class';
-  print blessed( $bar );      # prints "Class"
+  print blessed( $bar ) // 'not blessed';    # prints "Class"
 
   $bar = "some other value";
-  print blessed( $bar );      # prints undef
+  print blessed( $bar ) // 'not blessed';    # prints "not blessed"
 
 When we call C<bless> on a variable, we are actually blessing the
 underlying data structure that the variable refers to. We are not
@@ -179,12 +179,12 @@ Each package contains a special array called C<@ISA>. The C<@ISA> array
 contains a list of that class's parent classes, if any. This array is
 examined when Perl does method resolution, which we will cover later.
 
-It is possible to manually set C<@ISA>, and you may see this in older
-Perl code. Much older code also uses the L<base> pragma. For new code,
-we recommend that you use the L<parent> pragma to declare your parents.
-This pragma will take care of setting C<@ISA>.  It will also load the
-parent classes and make sure that the package doesn't inherit from
-itself.
+Calling methods from a package means it must be loaded, of course, so
+you will often want to load a module and add it to C<@ISA> at the same
+time. You can do so in a single step using the L<parent> pragma.
+(In older code you may encounter the L<base> pragma, which is nowadays
+discouraged except when you have to work with the equally discouraged
+L<fields> pragma.)
 
 However the parent classes are set, the package's C<@ISA> variable will
 contain a list of those parents. This is simply a list of scalars, each
@@ -232,7 +232,7 @@ object (or class name), and the right hand side is the method name.
   my $pod = File->new( 'perlobj.pod', $data );
   $pod->save();
 
-The C<< -> >> syntax is also used when dereferencing a reference.  It
+The C<< -> >> syntax is also used when dereferencing a reference. It
 looks like the same operator, but these are two different operations.
 
 When you call a method, the thing on the left side of the arrow is
@@ -325,14 +325,12 @@ methods.
   sub speak {
       my $self = shift;
 
-      $self->SUPER::speak();
-
       say 'A';
   }
 
   package B;
 
-  use parent 'A';
+  use parent -norequire, 'A';
 
   sub speak {
       my $self = shift;
@@ -344,7 +342,7 @@ methods.
 
   package C;
 
-  use parent 'B';
+  use parent -norequire, 'B';
 
   sub speak {
       my $self = shift;
@@ -491,8 +489,8 @@ As you can see, we've stored the path and file data in the object
 itself. Remember, under the hood, this object is still just a hash.
 Later, we'll write accessors to manipulate this data.
 
-For our File::MP3 class, we can check to make sure that the path we're
-given ends with ".mp3":
+For our C<File::MP3> class, we can check to make sure that the path
+we're given ends with ".mp3":
 
   package File::MP3;
 
@@ -583,6 +581,34 @@ X<method>
 Perl supports several other ways to call methods besides the C<<
 $object->method() >> usage we've seen so far.
 
+=head3 Method Names with a Fully Qualified Name
+
+Perl allows you to call methods using their fully qualified name (the
+package and method name):
+
+  my $mp3 = File::MP3->new( 'Regin.mp3', $data );
+  $mp3->File::save();
+
+When you a fully qualified method name like C<File::save>, the method
+resolution search for the C<save> method starts in the C<File> class,
+skipping any C<save> method the C<File::MP3> class may have defined. It
+still searches the C<File> class's parents if necessary.
+
+While this feature is most commonly used to explicitly call methods
+inherited from an ancestor class, there is no technical restriction
+that enforces this:
+
+  my $obj = Tree->new();
+  $obj->Dog::bark();
+
+This calls the C<bark> method from class C<Dog> on an object of class
+C<Tree>, even if the two classes are completely unrelated. Use this
+with great care.
+
+The C<SUPER> pseudo-class that was described earlier is I<not> the same
+as calling a method with a fully-qualified name. See the earlier
+L</Inheritance> section for details.
+
 =head3 Method Names as Strings
 
 Perl lets you use a scalar variable containing a string as a method
@@ -626,7 +652,7 @@ this idiom in the wild combined with a call to C<can>:
       $object->$meth();
   }
 
-=head3 Deferencing Method Call
+=head3 Dereferencing Method Call
 
 Perl also lets you use a dereferenced scalar reference in a method
 call. That's a mouthful, so let's look at some code:
@@ -634,7 +660,7 @@ call. That's a mouthful, so let's look at some code:
   $file->${ \'save' };
   $file->${ returns_scalar_ref() };
   $file->${ \( returns_scalar() ) };
-  $file->${ returns_sub_ref() };
+  $file->${ returns_ref_to_sub_ref() };
 
 This works if the dereference produces a string I<or> a subroutine
 reference.
@@ -687,10 +713,10 @@ thing as well:
 =head3 Indirect Object Syntax
 X<indirect object>
 
-B<Outside of the file handle case, use of this syntax is discouraged,
-as it can confuse the Perl interpreter. See below for more details.>
+B<Outside of the file handle case, use of this syntax is discouraged as
+it can confuse the Perl interpreter. See below for more details.>
 
-Perl suports another method invocation syntax called "indirect object"
+Perl supports another method invocation syntax called "indirect object"
 notation. This syntax is called "indirect" because the method comes
 before the object it is being invoked on.
 
@@ -877,7 +903,7 @@ you want to refer to do it without a package name prefix under C<strict
 Without the C<our $AUTOLOAD> declaration, this code will not compile
 under the L<strict> pragma.
 
-As the comment says, this is not a good way to implement accessors. 
+As the comment says, this is not a good way to implement accessors.
 It's slow and too clever by far. However, you may see this as a way to
 provide accessors in older Perl code. See L<perlootut> for
 recommendations on OO coding in Perl.
@@ -913,7 +939,7 @@ then the error will change the value of C<$@>.
 Because C<DESTROY> methods can be called at any time, you should
 localize any global variables you might update in your C<DESTROY>. In
 particular, if you use C<eval {}> you should localize C<$@>, and if you
-use C<system> or backticks, you should localize C<$?>.
+use C<system> or backticks you should localize C<$?>.
 
 If you define an C<AUTOLOAD> in your class, then Perl will call your
 C<AUTOLOAD> to handle the C<DESTROY> method. You can prevent this by
@@ -951,7 +977,7 @@ C<Devel::GlobalDestruction> module on CPAN.
 
 If your C<DESTROY> method issues a warning during global destruction,
 the Perl interpreter will append the string " during global
-destruction" the warning.
+destruction" to the warning.
 
 During global destruction, Perl will always garbage collect objects
 before unblessed references. See L<perlhacktips/PERL_DESTRUCT_LEVEL>