From: Rafael Garcia-Suarez <rgarciasuarez@gmail.com>
Date: Thu, 6 Jul 2006 13:36:57 +0000 (+0000)
Subject: Mention state variables in perldiag. Add switch-related keywords
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=36fb85f3330d45eeaf9d312c267fad71d5354c6c;p=p5sagit%2Fp5-mst-13.2.git

Mention state variables in perldiag. Add switch-related keywords
in the keyword listing section in perlfunc. Add a summary of
C<state> in perlfunc. Fix a typo in the synopsis for C<our>.
Don't say that C<my $_> is illegal in perlsub.

p4raw-id: //depot/perl@28491
---

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 93c8767..8228cf9 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1422,13 +1422,18 @@ conditional. Some people have exploited this bug to achieve a kind of
 static variable. Since we intend to fix this bug, we don't want people
 relying on this behavior. You can achieve a similar static effect by
 declaring the variable in a separate block outside the function, eg
-    
+
     sub f { my $x if 0; return $x++ }
 
 becomes
 
     { my $x; sub f { return $x++ } }
 
+Beginning with perl 5.9.4, you can also use C<state> variables to
+have lexicals that are initialized only once (see L<feature>):
+
+    sub f { state $x; return $x++ }
+
 =item DESTROY created new reference to dead object '%s'
 
 (F) A DESTROY() method created a new reference to the object which is
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 41f19a8..180c481 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -158,19 +158,23 @@ C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
 =item Keywords related to switch
 
-C<break>, C<continue>
+C<break>, C<continue>, C<given>, C<when>, C<default>
 
 (These are only available if you enable the "switch" feature.
 See L<feature> and L<perlsyn/"Switch statements">.)
 
 =item Keywords related to scoping
 
-C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
+C<caller>, C<import>, C<local>, C<my>, C<our>, C<state>, C<package>,
+C<use>
+
+(C<state> is only available if the "state" feature is enabled. See
+L<feature>.)
 
 =item Miscellaneous functions
 
-C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
-C<scalar>, C<undef>, C<wantarray>
+C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>,
+C<state>, C<reset>, C<scalar>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
 X<process> X<pid> X<process id>
@@ -229,8 +233,10 @@ X<perl5>
 
 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
 C<import>, C<lc>, C<lcfirst>, C<lock>, C<map>, C<my>, C<no>, C<our>,
+C<state>,
 C<prototype>, C<qr>, C<qw>, C<qx>, C<readline>, C<readpipe>, C<ref>,
-C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
+C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>,
+C<break>, C<continue>, C<given>, C<when>, C<default>
 
 * - C<sub> was a keyword in perl4, but in perl5 it is an
 operator, which can be used in expressions.
@@ -3429,7 +3435,7 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 =item our EXPR
 X<our> X<global>
 
-=item our EXPR TYPE
+=item our TYPE EXPR
 
 =item our EXPR : ATTRS
 
@@ -5957,6 +5963,23 @@ See your native chmod(2) and stat(2) documentation for more details
 about the C<S_*> constants.  To get status info for a symbolic link
 instead of the target file behind the link, use the C<lstat> function.
 
+=item state EXPR
+X<state>
+
+=item state TYPE EXPR
+
+=item state EXPR : ATTRS
+
+=item state TYPE EXPR : ATTRS
+
+C<state> declares a lexically scoped variable, just like C<my> does.
+However, those variables will be initialized only once, contrary to
+lexical variables that are reinitialized each time their enclosing block
+is entered.
+
+C<state> variables are only enabled when the C<feature 'state'> pragma is
+in effect.  See L<feature>.
+
 =item study SCALAR
 X<study>
 
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 71d6691..082d520 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -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