=cut outside of pod section causes rest of file to be treated as pod

[djerius]

Description

A =cut outside of an actual section of pod causes the parser to switch into pod mode. This is technically correct, according to the docs:

A Pod block starts with any command paragraph

but this behavior for =cut seems counterintuitive.

(As to why a lone =cut might be there; I have a here-doc containing snippets of pod, and podspell gets confused and doesn't know when the pod ends).

Steps to Reproduce

This code

sub foo {
=cut      
}

produces

Missing right curly or square bracket at foo.pl line 7, at end of line
syntax error at foo.pl line 7, at EOF
foo.pl had compilation errors.

Expected behavior

I expected the parser to recognize that the =cut was a no-op.

Perl configuration

Summary of my perl5 (revision 5 version 40 subversion 3) configuration:
   
  Platform:
    osname=linux
    osvers=6.12.33+deb12-amd64
    archname=x86_64-linux
    uname='linux leafhopper 6.12.33+deb12-amd64 #1 smp preempt_dynamic debian 6.12.33-1~bpo12+1 (2025-07-09) x86_64 gnulinux '
    config_args='-Dprefix=/home/dj/.plenv/versions/5.40.3 -de -Dversiononly -A'eval:scriptdir=/home/dj/.plenv/versions/5.40.3/bin''
    hint=recommended
    useposix=true
    d_sigaction=define
    useithreads=undef
    usemultiplicity=undef
    use64bitint=define
    use64bitall=define
    uselongdouble=undef
    usemymalloc=n
    default_inc_excludes_dot=define
  Compiler:
    cc='cc'
    ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -D_FORTIFY_SOURCE=2'
    optimize='-O2'
    cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
    ccversion=''
    gccversion='12.2.0'
    gccosandvers=''
    intsize=4
    longsize=8
    ptrsize=8
    doublesize=8
    byteorder=12345678
    doublekind=3
    d_longlong=define
    longlongsize=8
    d_longdbl=define
    longdblsize=16
    longdblkind=3
    ivtype='long'
    ivsize=8
    nvtype='double'
    nvsize=8
    Off_t='off_t'
    lseeksize=8
    alignbytes=8
    prototype=define
  Linker and Libraries:
    ld='cc'
    ldflags =' -fstack-protector-strong -L/usr/local/lib'
    libpth=/usr/local/lib /usr/lib/x86_64-linux-gnu /usr/lib /usr/lib64
    libs=-lpthread -ldl -lm -lcrypt -lutil -lc
    perllibs=-lpthread -ldl -lm -lcrypt -lutil -lc
    libc=/lib/x86_64-linux-gnu/libc.so.6
    so=so
    useshrplib=false
    libperl=libperl.a
    gnulibc_version='2.36'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs
    dlext=so
    d_dlsymun=undef
    ccdlflags='-Wl,-E'
    cccdlflags='-fPIC'
    lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong'


Characteristics of this binary (from libperl): 
  Compile-time options:
    HAS_LONG_DOUBLE
    HAS_STRTOLD
    HAS_TIMES
    PERLIO_LAYERS
    PERL_COPY_ON_WRITE
    PERL_DONT_CREATE_GVSV
    PERL_HASH_FUNC_SIPHASH13
    PERL_HASH_USE_SBOX32
    PERL_MALLOC_WRAP
    PERL_OP_PARENT
    PERL_PRESERVE_IVUV
    PERL_USE_SAFE_PUTENV
    USE_64_BIT_ALL
    USE_64_BIT_INT
    USE_LARGE_FILES
    USE_LOCALE
    USE_LOCALE_COLLATE
    USE_LOCALE_CTYPE
    USE_LOCALE_NUMERIC
    USE_LOCALE_TIME
    USE_PERLIO
    USE_PERL_ATOF
  Built under linux
  Compiled at Aug  6 2025 22:51:11
  %ENV:
    PERL_CPANM_OPT="--cascade-search --mirror-only  --mirror /home/dj/Work/darkpan --mirror http://www.cpan.org"
    PERL_CPAN_MIRROR_TINY_BASE="/home/dj/Work/darkpan"
    PERL_DARKPAN="/home/dj/Work/darkpan"
  @INC:
    /home/dj/.plenv/versions/5.40.3/lib/perl5/site_perl/5.40.3/x86_64-linux
    /home/dj/.plenv/versions/5.40.3/lib/perl5/site_perl/5.40.3
    /home/dj/.plenv/versions/5.40.3/lib/perl5/5.40.3/x86_64-linux
    /home/dj/.plenv/versions/5.40.3/lib/perl5/5.40.3

[haarg]

I doubt we can change this without significant fallout.

[Grinnz]

=cut is a bit of an oddity among pod declarations. Most pod directives will slurp up any following lines until the next blank line, but =cut is defined as ending the pod processing on that line, also ignoring any further text on the same line. It is also specified that it should be an error to start a pod block with a =cut line, but this refers to Pod parsers, not Perl parsers which don't always match in behavior (due to also parsing the surrounding Perl code, and not concerning itself with Pod errors). https://perldoc.perl.org/perlpodspec#%22=cut%22

It is also noted that a blank line is recommended following =cut for "older Pod processors". https://perldoc.perl.org/perlpod#=cut

I would consider this a bug, and my suspicion is there isn't real-world impact, but this would at least need to be verified on CPAN before making changes.

[djerius]

I would consider this a bug, and my suspicion is there isn't real-world impact, but this would at least need to be verified on CPAN before making changes.

It's a rather bizarre corner case, to be sure. A 'do no harm' approach might be simply to document the behavior.

[haarg]

Changing this would introduce a disparity with many tools which try to strip pod or do similar jobs.

I've also seen =cut/=cut regions being used to temporarily comment out code.

[Grinnz]

There are already disparities with pod tools, and this might even be one of them, as a pod stripper following the rules of perlpodspec currently would only strip the =cut line in the given example.

[haarg]

A pod stripper will follow perl's rules for pod, not pod's

[Leont]

Would it be reasonable to make this warn?

[ap]

What would the warning say though? What would be the goal of the warning (what it’s trying to get the user to do)? It doesn’t seem to me that warning about the =cut itself would be terribly useful.

What possibly might make sense though is something analogous to “Might be a runaway multi-line X string starting on line Y” case, a bonus warning that you get after a parse error or related warning.

[ap]

@djerius If you are not targetting perls older than 5.26, the easy way out is an indented here-doc (<<~) so you can put some whitespace at the start of every line of your POD sample. If you are targetting at least 5.14, you can still do that somewhat conveniently with a =~ s/^\t//mgr tacked onto the here-doc operator (the /r is what makes this convenient and what requires 5.14).

[djerius]

the easy way out is an indented here-doc (<<~)

The code started pre 5.26, but now it is definitely post 5.26; I eventually stumbled upon on your approach when I investigated why the newer parts of the code, which use indented here-docs, weren't eliciting the same error.

Another approach (my first fix) is to add a =pod before the =cut, which also works, but is clumsy and requires a "do not remove this =pod" comment, see GH#23772" for future me.

The here-doc approach is more elegant. Thanks.