deal with assignment to $/ better, deprecate edge cases, and forbid others

The actual behavior of $/ under various settings and how it is documented
varies quite a bit. Clarify the documentation, and add various checks
that are validated when setting $/.

The gist of the problem was that the way that weirdo ref assignments were
handled was mostly broken:

  * setting to a reference to an array, hash, or other higher level
  construct would behave similarly to setting it to a reference to a
  an integer, by numifying the ref and using it as an integer. This
  behavior was entirely undocumented.

  * setting to a reference to 0 or to -1 was *documented* in triggering
  "slurp" behavior, but actually did not. Instead it would set the
  separator to the stringified form of the ref, which would *appear* as
  slurp behavior due to the unlikelihood of a file actually containing
  a string which matched, however was less efficient, and if someone's
  luck were *terrible* might actually behave as a split.

In the future we wish to support more sophisticated ways of setting the
input record separator, possibly supporting things like:

  $/= [ "foo", "bar" ];
  $/= qr/foo|bar/;

Accordingly this patch *forbids* the use of a non scalar ref, and raises
a fatal exception when one does so.

Additionally it treats non-positive refs *exactly* the same as assigning
undef, *including* ignoring the original value and setting $/ to undef.
The means the implementation now matches the documentation. However
since this might involve some crazy script changing in behavior (as one
can't fetch back the original ref from $/) I have added a warning in
category "deprecated" advising the user what has happened and
recommending setting to "undef" explicitly.

As far as I can tell this will only *break* code doing extremely dodgy
things with $/.

While putting together this patch I encountered numerous problems with
porting tests. First off was porting/podcheck.t, which failed test without
saying why or what to do, even under TEST_VERBOSE=1. Then when I did a
regen to update the exceptions database and then used that information
to try to fix the reported problems it seems that it does not work properly
anyway.  Specifically you aren't allowed to have a / in the interesting
parts of a L<> reference. If you replace the / with an E<0x2f> then the
link is valid POD, but podcheck.t then considers it a broken link. If
you then  replace the / in perdiag with E<0x2f> as well then
porting/diag.t complains that you have an undocumented diagnostic!

Accordingly I used the --regen option of podcheck.t to add exceptions to
the exception database. I have no idea if the pod is correctly formatted
or not.

1 files changed, 6 insertions, 1 deletions

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index dd1d0d693a..4dd4a549ff 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1404,7 +1404,12 @@ not reading from a record-oriented file (or your OS doesn't have
 record-oriented files), then you'll likely get a full chunk of data
 with every read.  If a record is larger than the record size you've
 set, you'll get the record back in pieces.  Trying to set the record
-size to zero or less will cause reading in the (rest of the) whole file.
+size to zero or less is deprecated and will cause $/ to have the value
+of "undef", which will cause reading in the (rest of the) whole file.
+
+As of 5.19.9 setting C<$/> to any other form of reference will throw a
+fatal exception. This is in preparation for supporting new ways to set
+C<$/> in the future.
 
 On VMS only, record reads bypass PerlIO layers and any associated
 buffering, so you must not mix record and non-record reads on the