pp_ctl.c - support $INC in require_file @inc hook

$INC is localized to be the C level index of the loop over the @inc
array. At the end of the hook its value is assigned back to the C level
loop iterator (inc_idx). This allows a hook to control where in the @inc
array the loop should continue, for instance -1 represents "reprocess
from the beginning" (and as a convenience so does undef). This can be
useful if the @inc array is modified by a hook. Normally we would just
"continue along", but this may or may not be the right thing to do, so we
let the user decide.

Author: demerphq

pp_ctl.c

@@ -4307,6 +4307,9 @@ S_require_file(pTHX_ SV *sv)
                         SvSetSV_nosteal(nsv,sv);
                     }
 
+                    SV * inc_idx_sv = save_scalar(PL_incgv);
+                    sv_setiv(inc_idx_sv,inc_idx);
+
                     ENTER_with_name("call_INC_hook");
                     SAVETMPS;
                     EXTEND(SP, 2);
@@ -4412,6 +4415,21 @@ S_require_file(pTHX_ SV *sv)
                     /* FREETMPS may free our filter_cache */
                     SvREFCNT_inc_simple_void(filter_cache);
 
+                    /*
+                     Let the hook override which @INC entry we visit
+                     next by setting $INC to a different value than it
+                     was before we called the hook. If they have
+                     completely rewritten the array they might want us
+                     to start traversing from the beginning, which is
+                     represented by -1. We use undef as an equivalent of
+                     -1. This can't be used as a way to call a hook
+                     twice, as we still dedupe.
+                     We have to do this before we LEAVE, as we localized
+                     $INC before we called the hook.
+                    */
+                    inc_idx_sv = GvSVn(PL_incgv);
+                    inc_idx = SvOK(inc_idx_sv) ? SvIV(inc_idx_sv) : -1;
+
                     PUTBACK;
                     FREETMPS;
                     LEAVE_with_name("call_INC_hook");

t/op/require_errors.t

@@ -330,7 +330,6 @@ like $@, qr/^Can't locate \Q$nonsearch\E at/,
         { }, 'INC hooks that overwrite @INC continue as expected (skips a and z)');
 }
 {
-    local $::TODO = "Pending new feature \$INC";
     # as of 5.37.7
     fresh_perl_like(
         '@INC = (sub { @INC=qw(a b); undef $INC }, "z"); '