This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document scalarref retvals of @INC hook
[perl5.git] / pod / perlfunc.pod
index 1acd6f2..11d187b 100644 (file)
@@ -5846,17 +5846,22 @@ Subroutine references are the simplest case.  When the inclusion system
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first a reference to itself, and the
 second the name of the file to be included (e.g., "F<Foo/Bar.pm>").  The
-subroutine should return either nothing or else a list of up to three 
+subroutine should return either nothing or else a list of up to four 
 values in the following order:
 
 =over
 
 =item 1
 
-A filehandle, from which the file will be read.  
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
 
 =item 2
 
+A filehandle, from which the file will be read.  
+
+=item 3
+
 A reference to a subroutine.  If there is no filehandle (previous item),
 then this subroutine is expected to generate one line of source code per
 call, writing the line into C<$_> and returning 1, then finally at end of
@@ -5865,7 +5870,7 @@ called to act as a simple source filter, with the line as read in C<$_>.
 Again, return 1 for each valid line, and 0 after all lines have been
 returned.
 
-=item 3
+=item 4
 
 Optional state for the subroutine.  The state is passed in as C<$_[1]>.  A
 reference to the subroutine itself is passed in as C<$_[0]>.