Implement name change in POD example; Chris Waggoner++.

[perl5.git] / pod / perlref.pod

diff --git a/pod/perlref.pod b/pod/perlref.pod
index f45a383..5f9ce0a 100644 (file)
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -24,7 +24,7 @@ Hard references are smart--they keep track of reference counts for you,
 automatically freeing the thing referred to when its reference count goes
 to zero.  (Reference counts for values in self-referential or
 cyclic data structures may not go to zero without a little help; see
-L<perlobj/"Two-Phased Garbage Collection"> for a detailed explanation.)
+L</"Circular References"> for a detailed explanation.)
 If that thing happens to be an object, the object is destructed.  See
 L<perlobj> for more about objects.  (In a sense, everything in Perl is an
 object, but we usually reserve the word for references to objects that
@@ -51,6 +51,19 @@ scalar is holding a reference, it always behaves as a simple scalar.  It
 doesn't magically start being an array or hash or subroutine; you have to
 tell it explicitly to do so, by dereferencing it.
 
+References are easy to use in Perl.  There is just one overriding
+principle: in general, Perl does no implicit referencing or dereferencing.
+When a scalar is holding a reference, it always behaves as a simple scalar.
+It doesn't magically start being an array or hash or subroutine; you have to
+tell it explicitly to do so, by dereferencing it.
+
+That said, be aware that Perl version 5.14 introduces an exception
+to the rule, for syntactic convenience.  Experimental array and hash container
+function behavior allows array and hash references to be handled by Perl as
+if they had been explicitly syntactically dereferenced.  See
+L<perl5140delta/"Syntactical Enhancements">
+and L<perlfunc> for details.
+
 =head2 Making References
 X<reference, creation> X<referencing>
 
@@ -530,7 +543,7 @@ People frequently expect it to work like this.  So it does.
     ${$name x 2} = 3;          # Sets $foofoo
     $name->[0] = 4;            # Sets $foo[0]
     @$name = ();               # Clears @foo
-    &$name();                  # Calls &foo() (as in Perl 4)
+    &$name();                  # Calls &foo()
     $pack = "THAT";
     ${"${pack}::$name"} = 5;   # Sets $THAT::foo without eval
 
@@ -562,16 +575,16 @@ variables, which are all "global" to the package.
 
 =head2 Not-so-symbolic references
 
-A new feature contributing to readability in perl version 5.001 is that the
-brackets around a symbolic reference behave more like quotes, just as they
-always have within a string.  That is,
+Brackets around a symbolic reference can simply
+serve to isolate an identifier or variable name from the rest of an
+expression, just as they always have within a string.  For example,
 
     $push = "pop on ";
     print "${push}over";
 
 has always meant to print "pop on over", even though push is
-a reserved word.  This has been generalized to work the same outside
-of quotes, so that
+a reserved word.  This is generalized to work the same
+without the enclosing double quotes, so that
 
     print ${push} . "over";
 
@@ -579,8 +592,7 @@ and even
 
     print ${ push } . "over";
 
-will have the same effect.  (This would have been a syntax error in
-Perl 5.000, though Perl 4 allowed it in the spaceless form.)  This
+will have the same effect.  This
 construct is I<not> considered to be a symbolic reference when you're
 using strict refs:
 
@@ -588,9 +600,9 @@ using strict refs:
     ${ bareword };     # Okay, means $bareword.
     ${ "bareword" };   # Error, symbolic reference.
 
-Similarly, because of all the subscripting that is done using single
-words, we've applied the same rule to any bareword that is used for
-subscripting a hash.  So now, instead of writing
+Similarly, because of all the subscripting that is done using single words,
+the same rule applies to any bareword that is used for subscripting a hash.
+So now, instead of writing
 
     $array{ "aaa" }{ "bbb" }{ "ccc" }
 
@@ -734,5 +746,5 @@ Some pathological examples of the use of references can be found
 in the F<t/op/ref.t> regression test in the Perl source directory.
 
 See also L<perldsc> and L<perllol> for how to use references to create
-complex data structures, and L<perltoot>, L<perlobj>, and L<perlbot>
+complex data structures, and L<perlootut> and L<perlobj>
 for how to use them to create objects.