[perl #70836] Fix err msg for unterminated here-doc in eval

$ perl -e '<<foo'
Can't find string terminator "foo" anywhere before EOF at -e line 1.

$ perl -e 'eval "<<foo"; die $@'
Can't find string terminator "
foo" anywhere before EOF at (eval 1) line 1.

An internal implementation detail is leaking out.

When the lexer happens to have a multiline string in its line buffer
(in a string eval or quoted construct), it looks for "\nfoo" instead
of "foo".  It was passing that same string to the error-reporting code
(S_missingterm), resulting in that extraneous newline.
[perl #114040] Parse here-docs correctly in quoted constructs

When parsing code outside a string eval or quoted construct, the lexer
reads one line at a time into PL_linestr.

To parse a here-doc (hereinafter ‘deer hock’, because I spike lunar-
isms), the lexer has to pull extra lines out of the input stream ahead
of the current line, the value of PL_linestr remaining the same.

In a string eval, the entire piece of code being parsed is in
PL_linestr.

To parse a deer hock inside a string eval, the lexer has to fiddle
with the contents of PL_linestr, scanning for newline characters.

Originally, S_scan_heredoc just followed those two approaches.

When the lexer encounters a quoted construct, it looks for the end-
ing delimiter (reading from the input stream if necessary), puts the
entire quoted thing (minus quotes) in PL_linestr, and then starts an
inner lexing scope.

This means that deer hocks would not nest properly outside of a string
eval, because the body of the inner deer hock would be pulled out of
the input stream *after* the outer deer hock.

Larry Wall fixed that in commit fd2d095329 (Jan. 1997), so that this
would work:

<<foo
${\<<bar}
ber
bar
foo

He did so by following the string eval approach (looking for the deer
hock body in PL_linestr) if the deer hock was inside another quoted
construct.

Later, commit a2c066523a (Mar. 1998) fixed this:

s/^not /substr(<<EOF, 0, 0)/e;
  Ignored
EOF

by following the string eval approach only if the deer hock was inside
another non-backtick deer hock, not just any quoted construct.

The problem with the string eval approach inside a substitu-
tion is that it only looks in PL_linestr, which only contains
‘substr(<<EOF, 0, 0)’ when the lexer is handling the second part of
the s/// operator.

But that unfortunately broke this:

s/^not /substr(<<EOF, 0, 0)
  Ignored
EOF
 /e;

and this:

print <<`EOF`;
${\<<EOG}
echo stuff
EOG
EOF

reverting it to the pre-fd2d095329 behaviour, because the outer quoted
construct was treated as one line.

Later on, commit 0244c3a403 (Mar. 1999) fixed this:

eval 's/.../<<FOO/e
  stuff
FOO
';

which required a new approach not used before.  When the replacement
part of the s/// is being parsed, PL_linestr contains ‘<<FOO’.  The
body of the deer hock is not in the input stream (there isn’t one),
but in what was the previous value of PL_linestr before the lexer
encountered s///.

So 0244c3a403 fixed that by recording pointers into the outer string
and using them in S_scan_heredoc.  That commit, for some reason, was
written such that it applied only to substitutions, and not to other
quoted constructs.

It also failed to take interpolation into account, and did not record
the outer buffer position, but then tried to use it anyway, resulting
in crashes in both these cases:

eval 's/${ <<END }//';
eval 's//${ <<END }//';

It also failed to take multiline s///’s into account, resulting in
neither of these working, because it lost track of the current cursor,
leaving it at 'D' instead of the line break following it:

eval '
s//<<END
/e;
blah blah blah
END
;1' or die $@;

eval '
s//<<END
blah blah blah
END
/e;
;1' or die $@;

S_scan_heredoc currently positions the cursor (s) at the last charac-
ter of <<END if there is a line break on the same line.  There is an
s++ later on to account, but the code added by 0244c3a403 bypassed it.

So, in the end, deer hocks could only be nested in other quoted con-
structs if the outer construct was in a string eval and was not s///,
or was a non-backtick deer hock.

This commit hopefully fixes most of the problems. :-)

The s///-in-eval case is a little tricky.  We have to see whether the
deer hock label is on the last line of the s///.  If it is, we have
to peek into the outer buffer.  Otherwise, we have to treat it like a
string eval.

This commit does not deal with <<END inside the pattern of a multi-
line s/// or in nested quotes.
[perl #65838] Tests for here-docs without final newlines

and a few error cases
Clean up heredoc.t

* Made the tests more independent, mostly by decoupling the use of
  a single $string.  This will make it easier to expand on the test file
  later.

* Replace ok( $foo eq $bar ) with is() for better diagnostics

* Remove unnecessary STDERR redirection.  fresh_perl does that for you.

* fix fresh_perl to honor progfile and stderr arguments passed in
  rather than just blowing over them
heredoc.t: Suppress deprecation warnings
[perl #65838] Allow here-doc with no final newline

When reading a line of input while scanning a here-doc, if the line
does not end in \n, then we know we have reached the end of input.  By
simply tacking a \n on to the buffer, we can meet the expectations of
the rest of the here-doc parsing code.  If it turns out the delimiter
is not found on that line, it does not matter that we modified it, as
we will croak anyway.

I had to add a new flag to lex_next_chunk.  Before commit f0e67a1d2,
S_scan_heredoc would read from the stream itself, without closing any
handles.  So the next time through yylex, the eof code would supply
the final implicit semicolon.

Since f0e67a1d2, S_scan_heredoc has been calling lex_next_chunk, which
takes care of reading from the stream an supply any final ; at eof.
The here-doc parser will just get confused as a result (<<';' would
work without any terminator).  The new flag tells lex_next_chunk not
to do anything at eof (not even closing handles and resetting the
parser state), but to return false and leave everything as it was.
toke.c:S_scan_heredoc: Add comment about <<\FOO
heredoc after "" in s/// in eval

This works fine:

eval ' s//<<END.""/e; print
Just another Perl hacker,
END
'or die $@
__END__
Just another Perl hacker,

But this doesn’t:

eval ' s//"$1".<<END/e; print
Just another Perl hacker,
END
'or die $@
__END__
Can't find string terminator "END" anywhere before EOF at (eval 1) line 1.

It fails because PL_sublex_info.super_buf*, added by commit
0244c3a403, are not localised, so, after the "", s/// sees its own
buffer pointers in those variables, instead of its parent string eval.

This used to happen only with s///e inside s///e, but that was because
here-docs would peek inside the parent linestr buffer only inside
s///e, and not other quote-like operators.  That was fixed in
recent commits.

Simply moving the assignment of super_buf* into sublex_push does solve
the bug for a simple "", as "" does sublex_start, but not sublex_push.
We do need to localise those variables for "${\''}", however.
here-doc in quotes in multiline s//.../e in eval

When <<END occurs on the last line of a quote-like operator inside a
string eval ("${\<<END}"), it peeks into the linestr buffer of the
parent lexing scope (quote-like operators start a new lexing scope
with the linestr buffer containing what is between the quotes) to find
the body of the here-doc.  It modifies that buffer, stealing however
much it needs.

It was not leaving things in the consistent state that s///e checks
for when it finishes parsing the replacement (to make sure s//}+{/
doesn’t ‘work’).  Specifically, it was not shrinking the parent buf-
fer, so when PL_bufend was reset in sublex_done to the end of the par-
ent buffer, it was pointing to the wrong spot.
[perl #65838] perlop: remove caveat here-doc without newline
Don’t use strchr when scanning for newline after <<foo

The code that uses this is specifically for parsing <<foo inside a
quote-like operator inside a string eval.

This prints bar:

eval "s//<<foo/e
bar
foo
";
print $_ || $@;

This prints Can't find string terminator blah blah blah:

eval "s//<<foo/e #\0
bar
foo
";
print $_ || $@;

Nulls in comments are allowed elsewhere.  This prints bar:

eval "\$_ = <<foo #\0
bar
foo
";
print $_ || $@;

The problem with strchr is that it is specifically for scanning null-
terminated strings.  If embedded nulls are permitted (and should be in
this case), memchr should be used.

This code was added by 0244c3a403.
Fix here-docs in nested quote-like operators

When the lexer encounters a quote-like operator, it extracts the con-
tents of the quotes and starts an inner lexing scope.

To handle eval "s//<<FOO/e\n...", the here-doc parser peeks into the
outer lexing scope’s PL_linestr (current line buffer, which inside an
eval contains the entire string of code being parsed; for quote-like
operators, that is where the contents of the quote are stored).  It
only does this inside a string eval.  When parsing a file, the input
comes in one line at a time.  So the here-doc parser steals lines from
the input stream for s//<<FOO/e outside an eval.

This approach fails in this case, as the peekee is the linestr for
s///, not for the eval:

eval ' s//"${\<<END}"/e; print
Just another Perl hacker,
END
'or die $@
__END__
Can't find string terminator "END" anywhere before EOF at (eval 1) line 1.

We also need to do this peeking stuff outside of a string eval, to
solve this:

s//"${\<<END}"
Just another Perl hacker,
END
/e; print
__END__
Can't find string terminator "END" anywhere before EOF at - line 1.

In the first example above, we need to look not in the parent lexing
scope’s linestr, but in that of the grandparent.

To solve the second example, we need to check whether the outer lexing
scope is a quote-like operator when we are not in an eval.

For parsing here-docs in quotes in eval, we currently store two
things, the former buffer pointer and the former linestr, in
PL_sublex_info.super_{bufp,lines}tr.  The values for upper scopes are
stashed away on the savestack somewhere.

We need to be able to iterate through the outer lexer scopes till we
find one with multiple lines.  Retrieving the information from the
savestack would be too complex and error-prone.

Since PL_linestr is an SV, we can abuse a couple of fields in it.
Upgrading it to PVNV gives it both IVX and NVX fields, which are big
enough to store pointers.

IVX is already used to hold an op number.  So for the innermost quoted
scope we still need to use PL_sublex_info.super_bufptr.  When entering
a new lexing scope (in sublex_push), we can localise the IVX field of
the outer PL_linestr SV and set it to what PL_sublex_info.super_bufptr
was in that scope.  SvIVX(linestr) is only used for an op number when
that linestr’s lexing scope is the innermost one.

PL_sublex_info.super_linestr can be eliminated and replaced with
SvNVX(PL_linestr).
Fix substitution in substitution pattern

Guess what this prints:

s/${s|||, \""}Just another Perl hacker,
/anything/;
print

And look at this:

$ perl5.6.2 -e 's/${s|||;\""}/foo\n/; print;'
$ perl5.16.0 -e 's/${s|||;\""}/foo\n/; print;'
$ perl5.17.2 -e 's/${s|||;\""}/foo\n/; print;'
Bus error
$ ./miniperl -e 's/${s|||;\""}/foo\n/; print;'
Bus error

The first two gave no output, though they should have shown "foo".
And bleadperl now crashes.

When the lexer parses a quote-like operator, it begins by extracting
what is between the quotes.  It puts it in an SV stored in the varia-
ble PL_lex_stuff.  Then, if it is y/// or s///, it scans the replace-
ment part and puts it in an SV in PL_lex_repl.  When it finishes with
it, it sets PL_lex_repl to NULL.

Now, if you put s/// in the pattern part of s/// (or y in s), the
inner s/// will clobber PL_lex_repl with its own replacement string.
So, when the outer s/// finish parsing its pattern and wants its
replacement string.  If it is not there, it assumes it has already
parsed it (whether PL_lex_repl is set is how it remembers which half
of s/// it is parsing), and proceeds to feed bad code to the parser,
resulting in a bad op tree.

PL_lex_repl needs to be localised when a quote-like operator is
parsed.  Since localisation for quote-like operators happens in a sep-
arate yylex call (yylex calls sublex_push, which does it) after the
string delimiters are found, at which point PL_lex_repl has already
been set (clobbering the previous value), we change the delim-
iter-scanning code (scan_{str,trans,subst}) to use the new
PL_sublex_info.repl, which sublex_push now copies into PL_lex_repl
after localising the latter.
toke.c:scan_heredoc: Use PL_tokenbuf less

When scanning for a heredoc terminator in a string eval or quote-like
operator, the first character we are looking for is always a newline.
So instead of setting term to *PL_tokenbuf in those two code paths,
we can just hard-code '\n'.
smoke-me diag

nt,hun
perlop.pod: Update here-doc-in-quotes parsing rules
[Merge] Here-doc parsing

I was waiting for 5.17.3 to be released, before merging my work on
padlists (which is blocking lexical subs), since I thought it would be
mean to inflict it on blead at the last minute before a release.

So, in the mean time, I decided to fix a small here-doc parsing bug,
that prevented them from occurring inside regexp code blocks.

As often happens, it turned out to be more involved than that....

I ended up writing a history of here-doc parsing, which you can find
in the commit message for 5097bf9b8d, which shows that the way they
have interacted with other quote-like operators (or other here-docs)
has changed over time in interesting ways.

While I was fixing those, I started to find other bugs.  Since I was
modifying the code, I decided to try applying David Nicol’s patch that
allows a here-doc terminator with no newline after it, to avoid creat-
ing more conflicts through my changes.  The patch didn’t work.  And
while I was resolving what conflicts there were, I figured out a sim-
pler approach.  So, instead of trying to investigate into why the
patch didn’t work, I just wrote my own version, which used less code.
Instead of working back on error to try to see whether we could have
accepted a terminator without a newline, we can just tack a newline on
the string buffer at EOF and let the rest of the code handle it the
usual way.

I continued to find more bugs as I went, till my ‘Yay, another bug!’
started to become ‘What? *Another* bug?’.

In the end:

• I fixed here-doc parsing, such that the body starts on the line fol-
  lowing the <<foo marker, regardless of whether it is inside quotes,
  string evals, or what have you (but see remaining bugs below).  This
  was contrary to the documentation, but the documentation was actu-
  ally wrong half the time, so I corrected it.
• Here-doc terminators no longer require a final newline at EOF.
• You no longer get crashes with edge cases.
• Nulls in comments no longer confuse the here-doc parser.

And, finally, one bug that I fixed was not related to here-docs per
se, but got in the way.  It deserves its own JAPH:

s/${s|||, \""}Just another Perl hacker,
/anything/;
print

There are still two bugs remaining:
• Here-docs whose markers occur in single-line s/// patterns where the
  replacement part is multi-line or starts on a subsequent line are
  still screwed.
• CR and CR LF line terminators are treated inconsistently inside and
  outside of string evals.

I’ve decided to set those aside for later and merge what I’ve
done so far.