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 leading delimiter.
Leave a comment

2 Comments.

  1. so not <<-HERE like bash, just to be different

    • Do you really think that decision would be made “just to be different?” Or maybe what you mean is, “Bash does something like this with similar but different syntax. Why not use the same syntax?”

      The perl5 mailing list is full of discussion of syntax, so much so that it’s almost ridiculous. Syntax isn’t picked because the language designers are afraid of looking like some other language, but based on conversations about prior art.

      Often there’s more than one piece of prior art to consider. For example, did you know that ruby has an indented here-doc operator, spelled <<~? Which is going to have more users learning Perl 5, bash or Ruby? Tough question! Are the ruby and bash indented here-docs identical in behavior? Which is perl5's more like?

      Those are things that are considered when adding syntax. Not whether or not we can be weird.

Leave a Reply


[ Ctrl + Enter ]