From ca40957e468ea3b89ae69e8fca549bb1ad47b35f Mon Sep 17 00:00:00 2001
From: Father Chrysostomos <sprout@cpan.org>
Date: Sat, 15 Sep 2012 22:03:51 -0700
Subject: [PATCH] Document lexical subs

---
 lib/feature.pm         |  14 +++++++
 pod/perlexperiment.pod |   6 +++
 pod/perlsub.pod        | 101 +++++++++++++++++++++++++++++++++++++++++++++++++
 regen/feature.pl       |  14 +++++++
 4 files changed, 135 insertions(+)

diff --git a/lib/feature.pm b/lib/feature.pm
index 8afd53f..f585f16 100644
--- a/lib/feature.pm
+++ b/lib/feature.pm
@@ -230,6 +230,20 @@ See L<perlfunc/fc> for details.
 
 This feature is available from Perl 5.16 onwards.
 
+=head2 The 'lexical_subs' feature
+
+B<WARNING>: This feature is still experimental and the implementation may
+change in future versions of Perl.  For this reason, F<feature.pm> will
+warn when you enable the feature, unless you have explicitly disabled the
+warning:
+
+    no warnings "experimental:lexical_subs";
+
+This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
+and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
+
+This feature is available from Perl 5.18 onwards.
+
 =head1 FEATURE BUNDLES
 
 It's possible to load multiple features together, using
diff --git a/pod/perlexperiment.pod b/pod/perlexperiment.pod
index 1538452..ad88c06 100644
--- a/pod/perlexperiment.pod
+++ b/pod/perlexperiment.pod
@@ -256,6 +256,12 @@ See L<perlapi/PL_keyword_plugin> for the mechanism.
 
 Introduced in: Perl 5.11.2
 
+=item Lexical subroutines
+
+Introduced in: Perl 5.18
+
+See also: L<perlsub/Lexical Subroutines>
+
 =back
 
 =head2 Accepted features
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 2efd325..3bb1f0b 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -822,6 +822,107 @@ subroutine never gets that chance.  Consider;
 
 =back
 
+=head2 Lexical Subroutines
+X<my sub> X<state sub> X<our sub> X<subroutine, lexical>
+
+B<WARNING>: Lexical subroutines are still experimental and the
+implementation may change 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" warning 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.
+
+These subroutines are only visible within the block in which they are
+declared, and only after that declaration:
+
+    no warnings "experimental:lexical_subs";
+    use feature 'lexical_subs';
+
+    foo();		# calls the package/global subroutine
+    state sub foo {
+	foo();		# also calls the package subroutine
+    }
+    foo();		# calls "state" sub
+    my $ref = \&foo;	# take a reference to "state" sub
+
+    my sub bar { ... }
+    bar();		# calls "my" sub
+
+To use a lexical subroutine from inside the subroutine itself, you must
+predeclare it.  The C<sub foo {...}> subroutine definition syntax respects
+any previous C<my sub;> or C<state sub;> declaration.
+
+    my sub baz;		# predeclaration
+    sub baz {		# define the "my" sub
+	baz();		# recursive call
+    }
+
+=head3 C<state sub> vs C<my sub>
+
+What is the difference between "state" subs and "my" subs?  Each time that
+execution enters a block when "my" subs are declared, a new copy of each
+sub is created.  "State" subroutines persist from one execution of the
+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 {
+	    ... do something with $x ...
+	}
+	inner();
+    }
+
+In this example, a new C<$x> is created when C<whatever> is called, and
+also a new C<inner>, which can see the new C<$x>.  A "state" sub will only
+see the C<$x> from the first call to C<whatever>.
+
+=head3 C<our> subroutines
+
+Like C<our $variable>, C<our sub> creates a lexical alias to the package
+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 {
+	my sub foo { ... }
+	{
+	    # need to use the outer foo here
+	    our sub foo;
+	    foo();
+	}
+    }
+
+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 {
+	package DB;
+	() = caller 1;		# sets @DB::args
+	do_something(@args);	# uses MySneakyModule::do_something
+    }
+
 =head2 Passing Symbol Table Entries (typeglobs)
 X<typeglob> X<*>
 
diff --git a/regen/feature.pl b/regen/feature.pl
index cc7034e..da43f62 100755
--- a/regen/feature.pl
+++ b/regen/feature.pl
@@ -541,6 +541,20 @@ See L<perlfunc/fc> for details.
 
 This feature is available from Perl 5.16 onwards.
 
+=head2 The 'lexical_subs' feature
+
+B<WARNING>: This feature is still experimental and the implementation may
+change in future versions of Perl.  For this reason, F<feature.pm> will
+warn when you enable the feature, unless you have explicitly disabled the
+warning:
+
+    no warnings "experimental:lexical_subs";
+
+This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
+and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
+
+This feature is available from Perl 5.18 onwards.
+
 =head1 FEATURE BUNDLES
 
 It's possible to load multiple features together, using
-- 
2.7.4