What does the <<'m'=~m>> syntax mean in perl?

So I understand that perl has much unusual syntax, but I came across a code snippet at work that other day that has left me confused. Could someone please explain to me what it means:

<<'m'=~m>>
print $a unless $b;
return;
m
;

It looks like HEREDOC syntax, but not in any form I've ever seen.

This secret syntax is known as the ornate double-bladed sword, and is typically denoted as:

<<m=~m>>

Comments here

m
;

It is a hack for multi-line comments, making use of the heredoc syntax and match operator (=~) with > as delimiter.

Note, as slashes, /, aren't being used as the delimiter for matching, the 'm' operator is required. For example $my_var =~ /test/ is equivalent to $my_var =~ m>test>, whereas $my_var =~ >test> would be invalid.

Pay attention to the fact that the first m character in your snippet is enclosed by single quotes, meaning the $a and $b variables won't be interpolated. Had these quotes been omitted (as per my provided code example) perl would automatically add double quotes to the end marker and any subsequent variables would be interpolated. This would cause problems if $a and $b are no longer defined and you're using use warnings;.

To make the ornate double-blade example above easier to understand (but still not recommended), we could write:

<<"END" =~ //

Comments here

END
;

Note that the =~ // is redundant, so this is equivalent to:

<<"END";

Comments here

END

Which is just standard heredoc syntax in void context.

I would not recommend using this in production code as having a string in void context can cause problems. Plus this code is a head scratcher for even the most experienced perl programmers and is pointlessly difficult to read and maintain! If you want to create proper multi-line comments then I would suggest sticking to pod as explained here How do I enter a multi-line comment in Perl?

Hope this clears it up.

Running B::Deparse helps a lot in order to understand how perl is handling that piece of code (assuming it is at "test.pl" file):

perl -MO=Deparse  test.pl 

show us:

"print \$a unless \$b;\nreturn;\n" =~ //;
test.pl syntax OK

So, as you can see, perl is trying to match an empty regexpr to this string: "print \$a unless \$b;\nreturn;\n"