Clarify variable lists for my, our, state.

[perl5.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 1acd6f2..0b14d4c 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3758,19 +3758,19 @@ and C<IPC::SysV::Msg> documentation.
 
 Portability issues: L<perlport/msgsnd>.
 
-=item my EXPR
+=item my VARLIST
 X<my>
 
-=item my TYPE EXPR
+=item my TYPE VARLIST
 
-=item my EXPR : ATTRS
+=item my VARLIST : ATTRS
 
-=item my TYPE EXPR : ATTRS
+=item my TYPE VARLIST : ATTRS
 
 =for Pod::Functions declare and assign a local variable (lexical scoping)
 
 A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>.  If more than one value is listed,
+enclosing block, file, or C<eval>.  If more than one variable is listed,
 the list must be placed in parentheses.
 
 The exact semantics and interface of TYPE and ATTRS are still
@@ -3780,6 +3780,11 @@ from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
 L<attributes>, and L<Attribute::Handlers>.
 
+Note that with a parenthesised list, C<undef> can be used as a dummy
+placeholder, for example to skip assignment of initial values:
+
+    my ( undef, $min, $hour ) = localtime;
+
 =item next LABEL
 X<next> X<continue>
 
@@ -4322,14 +4327,14 @@ If EXPR is an empty string, returns 0.  If EXPR is omitted, uses C<$_>.
 For the reverse, see L</chr>.
 See L<perlunicode> for more about Unicode.
 
-=item our EXPR
+=item our VARLIST
 X<our> X<global>
 
-=item our TYPE EXPR
+=item our TYPE VARLIST
 
-=item our EXPR : ATTRS
+=item our VARLIST : ATTRS
 
-=item our TYPE EXPR : ATTRS
+=item our TYPE VARLIST : ATTRS
 
 =for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping)
 
@@ -4346,7 +4351,7 @@ the lexical scope of the C<our> declaration.  In this way, C<our> differs from
 C<use vars>, which allows use of an unqualified name I<only> within the
 affected package, but across scopes.
 
-If more than one value is listed, the list must be placed
+If more than one variable is listed, the list must be placed
 in parentheses.
 
     our $foo;
@@ -4395,6 +4400,11 @@ from Perl 5.8.0, also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
 L<attributes>, and L<Attribute::Handlers>.
 
+Note that with a parenthesised list, C<undef> can be used as a dummy
+placeholder, for example to skip assignment of initial values:
+
+    our ( undef, $min, $hour ) = localtime;
+
 =item pack TEMPLATE,LIST
 X<pack>
 
@@ -5846,17 +5856,22 @@ Subroutine references are the simplest case.  When the inclusion system
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first a reference to itself, and the
 second the name of the file to be included (e.g., "F<Foo/Bar.pm>").  The
-subroutine should return either nothing or else a list of up to three 
+subroutine should return either nothing or else a list of up to four 
 values in the following order:
 
 =over
 
 =item 1
 
-A filehandle, from which the file will be read.  
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
 
 =item 2
 
+A filehandle, from which the file will be read.  
+
+=item 3
+
 A reference to a subroutine.  If there is no filehandle (previous item),
 then this subroutine is expected to generate one line of source code per
 call, writing the line into C<$_> and returning 1, then finally at end of
@@ -5865,7 +5880,7 @@ called to act as a simple source filter, with the line as read in C<$_>.
 Again, return 1 for each valid line, and 0 after all lines have been
 returned.
 
-=item 3
+=item 4
 
 Optional state for the subroutine.  The state is passed in as C<$_[1]>.  A
 reference to the subroutine itself is passed in as C<$_[0]>.
@@ -7538,14 +7553,14 @@ instead of the target file behind the link, use the C<lstat> function.
 
 Portability issues: L<perlport/stat>.
 
-=item state EXPR
+=item state VARLIST
 X<state>
 
-=item state TYPE EXPR
+=item state TYPE VARLIST
 
-=item state EXPR : ATTRS
+=item state VARLIST : ATTRS
 
-=item state TYPE EXPR : ATTRS
+=item state TYPE VARLIST : ATTRS
 
 =for Pod::Functions +state declare and assign a persistent lexical variable
 
@@ -7555,6 +7570,11 @@ lexical variables that are reinitialized each time their enclosing block
 is entered.
 See L<perlsub/"Persistent Private Variables"> for details.
 
+If more than one variable is listed, the list must be placed in
+parentheses. With a parenthesised list, C<undef> can be used as a
+dummy placeholder. However, since initialization of state variables in
+list context is currently not possible this would serve no purpose.
+
 C<state> variables are enabled only when the C<use feature "state"> pragma 
 is in effect, unless the keyword is written as C<CORE::state>.
 See also L<feature>.