When inserting a code reference into @INC (as described a bit more than halfway down the require docs), what should you return from your code to indicate to require that the request has been fully handled and it should not continue checking @INC in search of the file?

use 5.010;
use lib sub {say "Using $_[1]"; sub {$_ = "1;"; 0}}, sub {die};
use Blah;
say "Hi!";
__END__
Using Blah.pm
Hi!
[download]

That's a step in the right direction, at least, but return sub { $_ = "1;"; 0; }; (with or without the explicit return) gets me

Foo.pm did not return a true value at -e line 1.
[download]

...which is very odd, seeing as that's the exact same thing you're returning from your example code. Requiring any combination of Foo and Local::Foo without my sub in place works fine, so I'm fairly confident that the problem is with the sub, not the modules being loaded.

In case there's some other error I'm missing, here's the current version of the sub I'm inserting into @INC:

BEGIN { unshift @INC, \&require_local }

sub require_local {
    # Exit immediately if we're not processing overrides
    return if $core_only;

    my (undef, $filename) = @_;

    # Keep track of what files we've already seen to avoid infinite lo
+ops
    return if exists $already_seen{$filename};
    $already_seen{$filename}++;

    # We only want to check overrides in $base_namespace
    return unless $filename =~ /^$base_namespace/;

    # OK, that all passed, so we can load up the actual files
    # Get the original version first, then overlay the local version
    say STDERR "requiring $filename";
    require $filename;

    my $local_file = $filename;
    if ($base_namespace) {
        $local_file =~ s[^$base_namespace][${base_namespace}/Local];
    } else {
        # Empty base namespace is probably a bad idea, but it should b
+e
        # handled anyhow
        $local_file = 'Local/' . $local_file;
    }
    $already_seen{$local_file}++;
    say STDERR "requiring $local_file";
    # Failure to load local version is not fatal, since it may not exi
+st
    no warnings 'redefine';
    eval { require $local_file };

    say STDERR "Done.";

    return sub { $_ = "1;"; 0; };
}
[download]

All three messages are appear on STDOUT, along with the subroutine redefined warning for the sub I've duplicated in Local/Foo.pm, so the sub is definitely running all the way through. It just seems to be returning a false value. (I also tried return sub { $_ = "1;"; 1; }; and, as I expected, it went into an infinite loop waiting for the returned sub to declare EOF.)

What version of perl did you test that with? On

This is perl, v5.10.1 (*) built for i686-linux-gnu-thread-multi
(with 40 registered patches, see perl -V for more detail)
[download]

(it's the default system perl from latest Ubuntu) your example doesn't seem to be working for me:

$ perl -E 'use lib sub {say "Using $_[1]"; sub {$_ = "1;"; 0}}, sub {d
+ie}; use Blah; say "Hi!";'
Using Blah.pm
Blah.pm did not return a true value at -e line 1.
BEGIN failed--compilation aborted at -e line 1.
[download]

Tested to be working on all versions of 5.12.

As I understand the require-docs, returning undef as first parameter will automatically lead to continuation of @INC inspection:

If an empty list, undef, or nothing that matches the first 3 values above is returned, then require looks at the remaining elements of @INC

You should either give it a file handle as first parameter, or no first parameter at all

Please expand on how you would go about returning a second parameter with "no first parameter at all". As far as I can tell, (undef, ...) is identical to (but more convenient than) creating an empty array and setting its second element while leaving the first untouched:

#!/usr/bin/env perl

use Data::Dumper;

my @a1 = (undef, 'second');
my @a2;
@a2[1] = 'second';

print Dumper(\@a1, \@a2);
__END__
Outputs:
$VAR1 = [
          undef,
          'second'
        ];
$VAR2 = [
          undef,
          'second'
        ];
[download]

Ah yes, I should have been more exact. What I meant was giving the subroutine pointer as first parameter, leaving out the nominal first paramter, the filehandle, completely. In other words no undef at all and the subroutine reference is promoted to first parameter.

4635 t/op/inccode.t                  See if coderefs work in @INC
[download]

t/op/inccode.t                  See if coderefs work in @INC

Ah, good find! I'll definitely take a look at the tests to see what enlightenment they might convey.

Going through inccode.t, I was able to get it working by returning an in-memory filehandle pointed to the string "1":

use PerlIO::Scalar;  # to avoid recursion when creating $fh

sub require_local {
  # do the actual work, per the source I posted earlier
  # ...

  open my $fh, '<', \'1';
  return $fh;
}
[download]

Thanks for finding those tests and pointing me at them!