Re: [PATCH] Tests are good

[perl5.git] / pod / perlsub.pod

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 9976316..4329c16 100644 (file)
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -169,8 +169,8 @@ Do not, however, be tempted to do this:
 
 Like the flattened incoming parameter list, the return list is also
 flattened on return.  So all you have managed to do here is stored
-everything in C<@a> and made C<@b> an empty list.  See L<Pass by
-Reference> for alternatives.
+everything in C<@a> and made C<@b> an empty list.  See 
+L<Pass by Reference> for alternatives.
 
 A subroutine may be called using an explicit C<&> prefix.  The
 C<&> is optional in modern Perl, as are parentheses if the
@@ -207,8 +207,8 @@ core, as are modules whose names are in all lower case.  A
 function in all capitals is a loosely-held convention meaning it
 will be called indirectly by the run-time system itself, usually
 due to a triggered event.  Functions that do special, pre-defined
-things include C<BEGIN>, C<CHECK>, C<INIT>, C<END>, C<AUTOLOAD>, and
-C<DESTROY>--plus all functions mentioned in L<perltie>.
+things include C<BEGIN>, C<CHECK>, C<INIT>, C<END>, C<AUTOLOAD>,
+C<CLONE> and C<DESTROY>--plus all functions mentioned in L<perltie>.
 
 =head2 Private Variables via my()
 
@@ -645,10 +645,6 @@ and in:
 
 all the subroutines are called in a list context.
 
-The current implementation does not allow arrays and hashes to be
-returned from lvalue subroutines directly.  You may return a
-reference instead.  This restriction may be lifted in future.
-
 =head2 Passing Symbol Table Entries (typeglobs)
 
 B<WARNING>: The mechanism described in this section was originally
@@ -697,9 +693,11 @@ Despite the existence of C<my>, there are still three places where the
 C<local> operator still shines.  In fact, in these three places, you
 I<must> use C<local> instead of C<my>.
 
-=over
+=over 4
+
+=item 1.
 
-=item 1. You need to give a global variable a temporary value, especially $_.
+You need to give a global variable a temporary value, especially $_.
 
 The global variables, like C<@ARGV> or the punctuation variables, must be 
 C<local>ized with C<local()>.  This block reads in F</etc/motd>, and splits
@@ -716,7 +714,9 @@ in C<@Fields>.
 It particular, it's important to C<local>ize $_ in any routine that assigns
 to it.  Look out for implicit assignments in C<while> conditionals.
 
-=item 2. You need to create a local file or directory handle or a local function.
+=item 2.
+
+You need to create a local file or directory handle or a local function.
 
 A function that needs a filehandle of its own must use
 C<local()> on a complete typeglob.   This can be used to create new symbol
@@ -746,7 +746,9 @@ a local alias.
 See L<perlref/"Function Templates"> for more about manipulating
 functions by name in this way.
 
-=item 3. You want to temporarily change just one element of an array or hash.
+=item 3.
+
+You want to temporarily change just one element of an array or hash.
 
 You can C<local>ize just one element of an aggregate.  Usually this
 is done on dynamics:
@@ -924,6 +926,22 @@ that absolutely must start with that character.  The value passed
 as part of C<@_> will be a reference to the actual argument given
 in the subroutine call, obtained by applying C<\> to that argument.
 
+You can also backslash several argument types simultaneously by using
+the C<\[]> notation:
+
+    sub myref (\[$@%&*])
+
+will allow calling myref() as
+
+    myref $var
+    myref @array
+    myref %hash
+    myref &sub
+    myref *glob
+
+and the first argument of myref() will be a reference to
+a scalar, an array, a hash, a code, or a glob.
+
 Unbackslashed prototype characters have special meanings.  Any
 unbackslashed C<@> or C<%> eats all remaining arguments, and forces
 list context.  An argument represented by C<$> forces scalar context.  An