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.

3 files changed, 20 insertions, 5 deletions

diff --git a/t/lib/warnings/9uninit b/t/lib/warnings/9uninit
index ce06b6b8d2..d9e5b9bed7 100644
--- a/t/lib/warnings/9uninit
+++ b/t/lib/warnings/9uninit
@@ -409,10 +409,9 @@ chomp $x; chop $x;
 my $y;
 chomp ($x, $y); chop ($x, $y);
 EXPECT
-Use of uninitialized value ${$/} in scalar chomp at - line 6.
-Use of uninitialized value ${$/} in chomp at - line 8.
-Use of uninitialized value ${$/} in chomp at - line 8.
-Use of uninitialized value $y in chomp at - line 8.
+Use of uninitialized value $m1 in scalar assignment at - line 4.
+Use of uninitialized value $m1 in scalar assignment at - line 4.
+Setting $/ to a reference to zero as a form of slurp is deprecated, treating as undef at - line 4.
 Use of uninitialized value $y in chop at - line 8.
 ########
 use warnings 'uninitialized';
diff --git a/t/lib/warnings/irs b/t/lib/warnings/irs
new file mode 100644
index 0000000000..9e1d3dea09
--- /dev/null
+++ b/t/lib/warnings/irs
@@ -0,0 +1,14 @@
+Test warnings related to $/
+__END__
+-w
+# warnable code, warnings enabled via command line switch
+$/ = \0;
+EXPECT
+Setting $/ to a reference to zero as a form of slurp is deprecated, treating as undef at - line 3.
+########
+-w
+# warnable code, warnings enabled via command line switch
+$/ = \-1;
+EXPECT
+Setting $/ to a reference to a negative integer as a form of slurp is deprecated, treating as undef at - line 3.
+
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 69f79ff64c..bb0c7d7a3c 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -232,7 +232,7 @@ pod/perlcygwin.pod	Verbatim line length including indents exceeds 79 by	25
 pod/perldebguts.pod	Verbatim line length including indents exceeds 79 by	34
 pod/perldebtut.pod	Verbatim line length including indents exceeds 79 by	22
 pod/perldebug.pod	Verbatim line length including indents exceeds 79 by	3
-pod/perldelta.pod	Apparent broken link	1
+pod/perldelta.pod	Apparent broken link	3
 pod/perldsc.pod	Verbatim line length including indents exceeds 79 by	4
 pod/perldtrace.pod	Verbatim line length including indents exceeds 79 by	26
 pod/perlebcdic.pod	Verbatim line length including indents exceeds 79 by	3
@@ -262,6 +262,7 @@ pod/perlos2.pod	? Should you be using L<...> instead of	2
 pod/perlos2.pod	Verbatim line length including indents exceeds 79 by	21
 pod/perlos390.pod	Verbatim line length including indents exceeds 79 by	11
 pod/perlperf.pod	Verbatim line length including indents exceeds 79 by	154
+pod/perlqnx.pod	Verbatim line length including indents exceeds 79 by	1
 pod/perlrun.pod	Verbatim line length including indents exceeds 79 by	3
 pod/perlsolaris.pod	Verbatim line length including indents exceeds 79 by	14
 pod/perlsource.pod	? Should you be using F<...> or maybe L<...> instead of	1
@@ -280,6 +281,7 @@ porting/todo.pod	Verbatim line length including indents exceeds 79 by	7
 utils/c2ph	Verbatim line length including indents exceeds 79 by	44
 lib/benchmark.pm	Verbatim line length including indents exceeds 79 by	2
 lib/config.pod	? Should you be using L<...> instead of	-1
+lib/config.pod	Verbatim line length including indents exceeds 79 by	5
 lib/extutils/embed.pm	Verbatim line length including indents exceeds 79 by	2
 lib/perl5db.pl	? Should you be using L<...> instead of	1
 lib/pod/text/overstrike.pm	Verbatim line length including indents exceeds 79 by	1