[PATCH] Clarify variable lists for my, our, state.

[p5pRT]

Migrated from rt.perl.org#90408 (status was 'resolved')

Searchable as RT90408$

[p5pRT]

From @sciurius

5.14 docs for my (and our, and state) specify the syntax​:

  my EXPR
  my TYPE EXPR
  my EXPR : ATTRS
  my TYPE EXPR : ATTRS

EXPR is too liberal, since it is restricted to expressions that
designate a variable or list of variables.

This patch changes the descriptions to​:

  my VARLIST
  my TYPE VARLIST
  my VARLIST : ATTRS
  my TYPE VARLIST : ATTRS

And, in the text​:

  VARLIST designates a variable, or parenthesised list of variables.

---

pod/perlfunc.pod | 26 +++++++++++++-------------
1 files changed, 13 insertions(+), 13 deletions(-)

[p5pRT]

From @sciurius

0001-Clarify-variable-lists-for-my-our-state.patch

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 2a1b20a..968a529 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3164,17 +3164,17 @@ C<pack("l! a*", $type, $message)>.  Returns true if successful,
 or false if there is an error.  See also the C<IPC::SysV>
 and C<IPC::SysV::Msg> documentation.
 
-=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
 
 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
@@ -3649,14 +3649,14 @@ 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
 
 C<our> associates a simple name with a package variable in the current
 package for use within the current scope.  When C<use strict 'vars'> is in
@@ -6480,14 +6480,14 @@ 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
+=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
 
 C<state> declares a lexically scoped variable, just like C<my> does.
 However, those variables will never be reinitialized, contrary to

[p5pRT]

From @gisle

On Thu May 12 01​:18​:38 2011, jv wrote​:

And, in the text​:

 VARLIST designates a variable\, or parenthesised list of variables\.

The parenthesised list also accepts 'undef'. I did not see this text in the patch itself.

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @tonycoz

On Thu May 12 01​:18​:38 2011, jv wrote​:

5.14 docs for my (and our, and state) specify the syntax​:

Hi Johan,

Are you interested in updating your patch to account for Gisle's comments?

Tony

[p5pRT]

From @sciurius

Are you interested in updating your patch to account for Gisle's comments?

Take 2...

[p5pRT]

From @sciurius

0001-Clarify-variable-lists-for-my-our-state.patch

From fcae3768c6e3c5892338372633cd97ccd94373e3 Mon Sep 17 00:00:00 2001
From: Johan Vromans <[email protected]>
Date: Mon, 24 Jun 2013 09:23:49 +0200
Subject: [PATCH] Clarify variable lists for my, our, state.

---
 pod/perlfunc.pod | 43 +++++++++++++++++++++++++++++--------------
 1 file changed, 29 insertions(+), 14 deletions(-)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 11d187b..0b14d4c 100644
--- 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>
 
@@ -7543,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
 
@@ -7560,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>.
-- 
1.7.11.7

[p5pRT]

From @sciurius

[Quoting Tony Cook via RT, on June 23 2013, 22​:13, in "[perl #90408] [PATCH"]

On Thu May 12 01​:18​:38 2011, jv wrote​:

5.14 docs for my (and our, and state) specify the syntax​:

Hi Johan,

Are you interested in updating your patch to account for Gisle's comments?

Did you find and apply the (updated) patch?

[p5pRT]

From @cpansprout

On Mon Jun 24 00​:30​:31 2013, jv wrote​:

Are you interested in updating your patch to account for Gisle's
comments?

Take 2...

Thank you. Applied as 672208d.

--

Father Chrysostomos

[p5pRT]

@cpansprout - Status changed from 'open' to 'resolved'