X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=72b28f1add448ff31cdca3981780e774517aaade;hb=0c42fe95656e99f238a0bcf90ab2476c175615b7;hp=71d6691e38dcbca4b827be1af6b8d09760d2a14c;hpb=4358a253560c226dd674c77f83b913c071c4fa25;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 71d6691..72b28f1 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -227,10 +227,10 @@ indirectly by the run-time system itself, usually due to a triggered event.
 Subroutines that do special, pre-defined things include C<AUTOLOAD>, C<CLONE>,
 C<DESTROY> plus all functions mentioned in L<perltie> and L<PerlIO::via>.
 
-The C<BEGIN>, C<CHECK>, C<INIT> and C<END> subroutines are not so much
-subroutines as named special code blocks, of which you can have more
-than one in a package, and which you can B<not> call explicitly.  See
-L<perlmod/"BEGIN, CHECK, INIT and END">
+The C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> and C<END> subroutines
+are not so much subroutines as named special code blocks, of which you
+can have more than one in a package, and which you can B<not> call
+explicitly.  See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">
 
 =head2 Private Variables via my()
 X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
@@ -394,7 +394,6 @@ never fully qualified with the package name.  In particular, you're not
 allowed to try to make a package variable (or other global) lexical:
 
     my $pack::var;	# ERROR!  Illegal syntax
-    my $_;		# also illegal (currently)
 
 In fact, a dynamic variable (also known as package or global variables)
 are still accessible using the fully qualified C<::> notation even while a
@@ -432,7 +431,34 @@ L<perlref/"Function Templates"> for something of a work-around to
 this.
 
 =head2 Persistent Private Variables
-X<static> X<variable, persistent> X<variable, static> X<closure>
+X<state> X<state variable> X<static> X<variable, persistent> X<variable, static> X<closure>
+
+There are two ways to build persistent private variables in Perl 5.10.
+First, you can simply use the C<state> feature. Or, you can use closures,
+if you want to stay compatible with releases older than 5.10.
+
+=head3 Persistent variables via state()
+
+Beginning with perl 5.9.4, you can declare variables with the C<state>
+keyword in place of C<my>. For that to work, though, you must have
+enabled that feature beforehand, either by using the C<feature> pragma, or
+by using C<-E> on one-liners. (see L<feature>)
+
+For example, the following code maintains a private counter, incremented
+each time the gimme_another() function is called:
+
+    use feature 'state';
+    sub gimme_another { state $x; return ++$x }
+
+Also, since C<$x> is lexical, it can't be reached or modified by any Perl
+code outside.
+
+When combined with variable declaration, simple scalar assignment to C<state>
+variables (as in C<state $x = 42>) is executed only the first time.  When such
+statements are evaluated subsequent times, the assignment is ignored.  The
+behavior of this sort of assignment to non-scalar variables is undefined.
+
+=head3 Persistent variables with closures
 
 Just because a lexical variable is lexically (also called statically)
 scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
@@ -479,8 +505,9 @@ starts to run:
 	}
     }
 
-See L<perlmod/"BEGIN, CHECK, INIT and END"> about the
-special triggered code blocks, C<BEGIN>, C<CHECK>, C<INIT> and C<END>.
+See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> about the
+special triggered code blocks, C<BEGIN>, C<UNITCHECK>, C<CHECK>,
+C<INIT> and C<END>.
 
 If declared at the outermost scope (the file scope), then lexicals
 work somewhat like C's file statics.  They are available to all
@@ -1012,7 +1039,7 @@ corresponding built-in.
     sub myopen (*;$)	     myopen HANDLE, $name
     sub mypipe (**)	     mypipe READHANDLE, WRITEHANDLE
     sub mygrep (&@)	     mygrep { /foo/ } $a, $b, $c
-    sub myrand ($)	     myrand 42
+    sub myrand (;$)	     myrand 42
     sub mytime ()	     mytime
 
 Any backslashed prototype character represents an actual argument
@@ -1056,9 +1083,13 @@ follows:
 	...
     }
 
-A semicolon separates mandatory arguments from optional arguments.
+A semicolon (C<;>) separates mandatory arguments from optional arguments.
 It is redundant before C<@> or C<%>, which gobble up everything else.
 
+As the last character of a prototype, or just before a semicolon, you can
+use C<_> in place of C<$>: if this argument is not provided, C<$_> will be
+used instead.
+
 Note how the last three examples in the table above are treated
 specially by the parser.  C<mygrep()> is parsed as a true list
 operator, C<myrand()> is parsed as a true unary operator with unary
@@ -1270,10 +1301,9 @@ that understands regular expressions.
     sub glob {
 	my $pat = shift;
 	my @got;
-	local *D;
-	if (opendir D, '.') { 
-	    @got = grep /$pat/, readdir D; 
-	    closedir D;   
+	if (opendir my $d, '.') { 
+	    @got = grep /$pat/, readdir $d; 
+	    closedir $d;   
 	}
 	return @got;
     }
@@ -1325,7 +1355,8 @@ And, as you'll have noticed from the previous example, if you override
 C<glob>, the C<< <*> >> glob operator is overridden as well.
 
 In a similar fashion, overriding the C<readline> function also overrides
-the equivalent I/O operator C<< <FILEHANDLE> >>.
+the equivalent I/O operator C<< <FILEHANDLE> >>. Also, overriding
+C<readpipe> also overrides the operators C<``> and C<qx//>.
 
 Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden.