This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add perldelta entries for
[perl5.git] / pod / perlsub.pod
index 78de284..434bb8c 100644 (file)
@@ -98,8 +98,8 @@ Aside from an experimental facility (see L</Signatures> below),
 Perl does not have named formal parameters.  In practice all you
 do is assign to a C<my()> list of these.  Variables that aren't
 declared to be private are global variables.  For gory details
-on creating private variables, see L<"Private Variables via my()">
-and L<"Temporary Values via local()">.  To create protected
+on creating private variables, see L</"Private Variables via my()">
+and L</"Temporary Values via local()">.  To create protected
 environments for a set of functions in a separate package (and
 probably a separate file), see L<perlmod/"Packages">.
 X<formal parameter> X<parameter, formal>
@@ -192,7 +192,7 @@ 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> empty.  See 
-L<Pass by Reference> for alternatives.
+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
@@ -1056,20 +1056,20 @@ using the CPAN module Sentinel or something similar.
 =head2 Lexical Subroutines
 X<my sub> X<state sub> X<our sub> X<subroutine, lexical>
 
-B<WARNING>: Lexical subroutines are still experimental.  The feature may be
-modified or removed in future versions of Perl.
-
-Lexical subroutines are only available under the C<use feature
-'lexical_subs'> pragma, which produces a warning unless the
-"experimental::lexical_subs" warnings category is disabled.
-
 Beginning with Perl 5.18, you can declare a private subroutine with C<my>
 or C<state>.  As with state variables, the C<state> keyword is only
 available under C<use feature 'state'> or C<use 5.010> or higher.
 
+Prior to Perl 5.26, lexical subroutines were deemed experimental and were
+available only under the C<use feature 'lexical_subs'> pragma.  They also
+produced a warning unless the "experimental::lexical_subs" warnings
+category was disabled.
+
 These subroutines are only visible within the block in which they are
 declared, and only after that declaration:
 
+    # Include these two lines if your code is intended to run under Perl
+    # versions earlier than 5.26.
     no warnings "experimental::lexical_subs";
     use feature 'lexical_subs';
 
@@ -1102,9 +1102,6 @@ containing block to the next.
 So, in general, "state" subroutines are faster.  But "my" subs are
 necessary if you want to create closures:
 
-    no warnings "experimental::lexical_subs";
-    use feature 'lexical_subs';
-
     sub whatever {
        my $x = shift;
        my sub inner {
@@ -1125,9 +1122,6 @@ subroutine of the same name.
 The two main uses for this are to switch back to using the package sub
 inside an inner scope:
 
-    no warnings "experimental::lexical_subs";
-    use feature 'lexical_subs';
-
     sub foo { ... }
 
     sub bar {
@@ -1143,9 +1137,6 @@ and to make a subroutine visible to other packages in the same scope:
 
     package MySneakyModule;
 
-    no warnings "experimental::lexical_subs";
-    use feature 'lexical_subs';
-
     our sub do_something { ... }
 
     sub do_something_with_caller {
@@ -1591,14 +1582,14 @@ and someone has been calling it with an array or expression
 returning a list:
 
     func(@foo);
-    func( split /:/ );
+    func( $text =~ /\w+/g );
 
 Then you've just supplied an automatic C<scalar> in front of their
 argument, which can be more than a bit surprising.  The old C<@foo>
 which used to hold one thing doesn't get passed in.  Instead,
 C<func()> now gets passed in a C<1>; that is, the number of elements
-in C<@foo>.  And the C<split> gets called in scalar context so it
-starts scribbling on your C<@_> parameter list.  Ouch!
+in C<@foo>.  And the C<m//g> gets called in scalar context so instead of a
+list of words it returns a boolean result and advances C<pos($text)>.  Ouch!
 
 If a sub has both a PROTO and a BLOCK, the prototype is not applied
 until after the BLOCK is completely defined.  This means that a recursive