Excess =cut breaks module

[denishowe]

Should the following module load?

=cut

1;

=cut outside pod is obviously a mistake, but should be harmless. I didn't expect it to cause the rest of the file to be ignored. It should always mean "What follows is Perl source not pod", whether it is in pod or not. I would argue that, in a code section, =cut starts a pod section because it begins with = (and then ends it immediately). I therefore consider this to be a bug. Tested in ActivePerl 5.10 on Windows and Perl 5.8 on Linux.

[MidLifeXis]

The message I get when testing is

Foo.pm did not return a true value at -e line 1.
BEGIN failed--compilation aborted at -e line 1.

What this tells me is that the pod block was opened by the =cut directive, and is behaving as I would expect from my reading of perlpodspec.

From perlpodspec,

Pod content is contained in Pod blocks. A Pod block starts with a line that matches m/\A=[a-zA-Z]/, and continues up to the next line that matches m/\A=cut/ or up to the end of the file if there is no m/\A=cut/ line.

Since you are not currently within a pod block when the stray =cut is encountered, it treats it as starting a pod block.

The question then is if the specification should be changed, or left in its simpler form (a match of m/\A=[a-zA-Z]/ starts a pod block, and the next =cut or end of file ends it).

On the one hand, the current state requires that no stray =cut directives exist (at least if you expect the module to work as intended), and keeps the parser fairly simple. On the other hand, it sort of flies in the face of DWIMery. I would probably fall on the side of keeping the parser simple, and updating podchecker to check for this case (=cut starting a POD block), especially since it could actually indicate a missing start tag (code smell).

Update: Firm up my position.

[Marshall]

At work, I would treat this as a "meets spec", "request to modify spec/or program" - and the lowest level of priority "bug tracking" (according to the impact).

The "1;" at the end of a module is an executable statement! I think the OP got confused by the implications of this in an included module (the print statement in my test code perhaps makes it more clear what happens).

I am ambivalent as to whether anything needs to or should be done about this. I would probably opt for a doc update "don't do that" in the description of =cut. This is malformed program syntax with a perhaps somewhat obscure symptom.

I missed the details of what constitutes a "heading" in the specs, but my testing lead me to the same conclusion (the parser doesn't reject =cut as a "start of a block") based upon demonstrated behavior. When something "weird" is seen, often some very short test code can at least clarify what is happening.

[Marshall]

I was also able to replicate the problem. If you put 2 but not 3 "=cut" lines, it works. I guess somehow Perl figures that the first "=cut" is a heading.

#!/usr/bin/perl -w
use strict;

=cut
=cut
#=cut won't work with the 3rd one

print "after the cut\n";

[choroba]

According to the perlpod, =cut ends a pod block. From where do you get it should also start one?

[Anonymous Monk]

No, it is documented not to load, because its junk

perl doesn't care how pod is started, only how it ends

$ perldoc junk
No documentation found for "junk".

$ cat junk
=cut

=cut

=cut

print "what? \n";
__END__

$ perldoc junk
No documentation found for "junk".

$ perl junk

$ perl -MO=Deparse junk
junk syntax OK

$ perl -MPod::Simple::Checker -e  "exit Pod::Simple::Checker->filter(s
+hift)->any_errata_seen"  junk
junk -- POD ERRORS
Hey! The above document had some coding errors, which are explained be
+low:
Around line 1:
  =cut found outside a pod block.  Skipping to next block.
Around line 3:
  =cut found outside a pod block.  Skipping to next block.
Around line 5:
  =cut found outside a pod block.  Skipping to next block.