Strip leading spaces from here-docs with v5.26

Perl v5.26 allows you to indent heredocs, that special multi-line string quoting mechanism. In v5.24 and earlier, the content of any here-doc included the entire line with any leading whitespace might be there. That meant you typed here-docs in a way the broke the indention of the block that contained them. Perl 6 envisioned a way that this could work and now Perl 5 has stolen some of that.

In this example, I have a here-doc in a subroutine just to have another scope. The lines of the string start at the beginning of the line rather than the beginning of the indentation:

sub say_something {
	my $string =<<'HERE';
This line is not indented
Neither is this line
And the delimiter is not indented
HERE

	print $string;
	}

say_something();

That's a bit annoying to some people (and not a problem to some others). v5.26 (not yet released) allows you to modify the here-doc to strip leading whitespace. Put a ~ after the <<:

sub say_something {
	my $string =<<~'HERE';
		This line is not indented
		Neither is this line
		And the delimiter is not indented
		HERE

	print $string;
	}

say_something();

The parser looks at the space in front of the final delimiter and strips that much space:

This line is not indented
Neither is this line
And the delimiter is not indented

Any whitespace left over is part of the string:

sub say_something {
	my $string =<<~'HERE';
		This line is not indented
			But this line is indented
		And the delimiter is not indented
		HERE

	print $string;
	}

say_something();

The second line kept the space after the whitespace that was before the delimiter:

This line is not indented
	But this line is indented
And the delimiter is not indented

If each line does not start with at least that much space, it's a compile-time error. This won't work:

use v5.25;
sub say_something {

	my $string =<<~"TAB_BEFORE";
		This is the first line
Another line that is a compilation error
		This is the last line
	TAB_BEFORE

	say $string;
	}

You get an error at compile time (although in Perl 6 it tries to figure it out, which I don't think is a good solution):

Indentation on line 2 of here-doc doesn't match delimiter at 526.pl line 5.

The whitespace before the end delimiter must match exactly at the beginning of each line. You can mix tabs and spaces, but it won't try to figure out how many spaces are in a tab (although the answer is four).

This also means that you have to be careful about de-tabbing or en-tabbing code, or when you change indention levels. You might accidentally change the number of whitespace characters.

Things to Remember

• v5.26 allows insignificant leading whitespace from here-docs
• Use <<~ to start the whitespace-stripping version of the here-doc.
• The here-doc will strip the exact same whitespace before the final delimiter.