Document the %hash{$scalar} warning

diff --git a/op.c b/op.c
index 57c20ee..38ea5b7 100644 (file)
--- a/op.c
+++ b/op.c
@@ -1235,6 +1235,7 @@ Perl_scalar(pTHX_ OP *o)
                    assert(SvPOK(name));
                    sv_chop(name,SvPVX(name)+1);
                    if (key)
+       /* diag_listed_as: Scalar value %%s[%s] better written as $%s[%s] */
                        Perl_warner(aTHX_ packWARN(WARN_SYNTAX),
                                   "Scalar value %%%"SVf
                                   "%c%s%c better written as $%"SVf
@@ -1242,6 +1243,7 @@ Perl_scalar(pTHX_ OP *o)
                                    SVfARG(name), lbrack, key, rbrack,
                                    SVfARG(name), lbrack, key, rbrack);
                    else
+       /* diag_listed_as: Scalar value %%s[%s] better written as $%s[%s] */
                        Perl_warner(aTHX_ packWARN(WARN_SYNTAX),
                                   "Scalar value %%%"SVf"%c%"SVf
                                   "%c better written as $%"SVf

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index f25533b..1737325 100644 (file)
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -4613,6 +4613,28 @@ as a list, you need to look into how references work, because Perl will
 not magically convert between scalars and lists for you.  See
 L<perlref>.
 
+=item Scalar value %%s[%s] better written as $%s[%s]
+
+(W syntax) In scalar context, you've used an array index/value slice
+(indicated by %) to select a single element of an array.  Generally
+it's better to ask for a scalar value (indicated by $).  The difference
+is that C<$foo[&bar]> always behaves like a scalar, both in the value it
+returns and when evaluating its argument, while C<%foo[&bar]> provides
+a list context to its subscript, which can do weird things if you're
+expecting only one subscript.  When called in list context, it also
+returns the index (what C<&bar> returns) in addition to the value.
+
+=item Scalar value %%s{%s} better written as $%s{%s}
+
+(W syntax) In scalar context, you've used a hash key/value slice
+(indicated by %) to select a single element of a hash.  Generally it's
+better to ask for a scalar value (indicated by $).  The difference
+is that C<$foo{&bar}> always behaves like a scalar, both in the value
+it returns and when evaluating its argument, while C<@foo{&bar}> and
+provides a list context to its subscript, which can do weird things
+if you're expecting only one subscript.  When called in list context,
+it also returns the key in addition to the value.
+
 =item Search pattern not terminated
 
 (F) The lexer couldn't find the final delimiter of a // or m{}