Hold your horses: perllol now lies through its teeth

The perllol manpage is all full of lies now, and nobody 
bothered to fix when they wedged the weird (+) stuff in:

    If you wanted just to append to a row, you'd have
    to do something a bit funnier looking:

	# add new columns to an existing row
	push @{ $AoA[0] }, "wilma", "betty";

    Notice that I I<couldn't> say just:

	push $AoA[0], "wilma", "betty";  # WRONG!

    In fact, that wouldn't even compile.  How come?  Because the argument
    to push() must be a real array, not just a reference to such.

The thing it says is wrong isn't wrong any more -- except when it is. :(

    use v5.14;
    sub show(+) {
	require Dumpvalue;
	state $prettily = new Dumpvalue::
			    tick        => q("),
			    compactDump => 1,
			    veryCompact => 1,
			;
	dumpValues $prettily @_;
    }
    # Assign a list of array references to an array.
    my @AoA = (
	   [ "fred", "barney" ],
	   [ "george", "jane", "elroy" ],
	   [ "homer", "marge", "bart" ],
    );
    push $AoA[0], "wilma", "betty";  # WRONG!
    show @AoA;

This shows it's fine:

    0  ARRAY(0x80f9d0)
       0  0..3  "fred" "barney" "wilma" "betty"
       1  0..2  "george" "jane" "elroy"
       2  0..2  "homer" "marge" "bart"

**EXCEPT** it can't autovivify:

    % blead -e 'push $AoA[0], "wilma", "betty";'
    Not an ARRAY reference at -e line 1.
    Exit 255

Hm, hm, hm, hm.

We *really* shouldn't ship perllol all messed up 
and lying like this.

I know, I know: I "should" be the one to fix it.

And I probably shall.

But darn it, whoever keeps sticking all this funky stuff 
into Perl (like weak refs) really needs to take responsibility
for updating the documentation to go along with it.  Code
is awesome, but code that makes our documentation lie just
makes us look sloppy.   Or stupid.  

Now I wonder what all else is wrong in our documentation 
because of this magic automatic implicit dereffing.  

GRRR!

--tom

• Hold your horses: perllol now lies through its teeth by Tom Christiansen