Documentation needed? - `module_true` interferes with require return value

[wesQ3]

Description
Using feature module_true changes the return value of a required file but this is not shown in the require documentation. I expect that behavior if the required file isn't already returning a true value, but I did not expect it to alter what was already a true return value.

This is simple to work around with a no feature 'module_true' but I first had to realize that it was part of the 5.40 feature bundle. My project recently updated to 5.40 so this was the first migration I have written with the new feature bundle.

Steps to Reproduce
This demo shows the behavior I saw using DBIx::Class::DeploymentHandler. DeploymentHandler runs Perl migration scripts contained in a directory by wrapping each in a package and requireing it. The loaded migration script is expected to return a subref to be run by the DH DeployMethod. I was unable to return the subref until I disabled the module_true feature.

demo.pl

#! /usr/bin/env perl

use strict; use warnings;
use feature 'say';
use lib '.';
use Carp 'croak';
use Digest::MD5 'md5_hex';
use Try::Tiny;

# Adapted from lib/DBIx/Class/DeploymentHandler/DeployMethod/SQL/Translator.pm
sub _load_sandbox {
  my $_file = shift;
  $_file = "$_file";
  # my $_package = _generate_script_package_name($_file);
  my $_package = 'A::Package::'.md5_hex("$_file");
  my $fn = eval sprintf <<'END_EVAL', $_package;
package %s;
{
  our $app;
  $app ||= require $_file;
  if ( !$app && ( my $error = $@ || $! )) { die $error; }
  $app;
}
END_EVAL
  croak $@ if $@;
  croak "$_file should define an anonymous sub that takes a schema but it didn't!"
     unless ref $fn && ref $fn eq 'CODE';
  return $fn;
}
sub _run_perl {
  my ($filename, $versions) = @_;
  say "Running Perl from $filename";
  my $fn = _load_sandbox($filename);
  try {
     # $fn->($self->schema, $versions)
     $fn->()
  } catch {
     die "failed to run Perl in $filename: $_"
  };
  say "\n";
}

_run_perl('no_module_true.pl');
_run_perl('use_module_true.pl');

no_module_true.pl

#!/usr/bin/env perl

use v5.40; use warnings;
no feature 'module_true';

sub {
   say 'module_true disabled';
};

use_module_true.pl

#!/usr/bin/env perl

use v5.40; use warnings;

sub {
   say 'using module_true';
};

Expected behavior

According to the require doc the module_true feature simply allows you to "avoid the requirement" of returning a true value. I was already returning a truthy value so I was surprised that the feature clobbered my returned subref.

Perl configuration

This is perl 5, version 40, subversion 2 (v5.40.2) built for x86_64-linux

``` Summary of my perl5 (revision 5 version 40 subversion 2) configuration:

Platform:
osname=linux
osvers=6.8.0-51-generic
archname=x86_64-linux
uname='linux bigboss 6.8.0-51-generic #52-ubuntu smp preempt_dynamic thu dec 5 13:09:44 utc 2024 x86_64 x86_64 x86_64 gnulinux '
config_args='-Dprefix=/home/wes/.plenv/versions/5.40.2 -de -Dversiononly -A'eval:scriptdir=/home/wes/.plenv/versions/5.40.2/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'
optimize='-O2'
cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
ccversion=''
gccversion='13.3.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.39'
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 Apr 30 2025 13:58:29
@inc:
/home/wes/.plenv/versions/5.40.2/lib/perl5/site_perl/5.40.2/x86_64-linux
/home/wes/.plenv/versions/5.40.2/lib/perl5/site_perl/5.40.2
/home/wes/.plenv/versions/5.40.2/lib/perl5/5.40.2/x86_64-linux
/home/wes/.plenv/versions/5.40.2/lib/perl5/5.40.2

</details>

[Leont]

You should not rely on anything but truthiness of the return value of require. Primarily because it's not actually saved, and the second time you require that module you'll get a 1 anyway regardless of module_true. I'm not terribly fond of that behavior either but it's very well established at this point.

This sounds like you should be using do instead of require TBH.

[jkeenan]

You should not rely on anything but truthiness of the return value of require. Primarily because it's not actually saved, and the second time you require that module you'll get a 1 anyway regardless of module_true.

Should we add something about require's return value (or absence thereof) to the docs?