t/op/grep.t using test.pl

[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d638cc1..99291d4 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4534,9 +4534,42 @@ 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 being 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 C<undef> or a filehandle, from which the file to
-include will be read.  If C<undef> is returned, C<require> will look at
-the remaining elements of @INC.
+subroutine should return nothing, or a list of up to 4 values in the
+following order:
+
+=over
+
+=item 1
+
+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 file handle, then this subroutine
+is expected to generate one line of source code per call, writing the line
+into C<$_> and returning 1, then returning 0 at "end of FILE" If there is a
+file handle then the subroutine will be called to act 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 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]>.
+
+=back
+
+If an empty list, C<undef>, or nothing that matches the first 3 values above
+is returned then C<require> will look at the remaining elements of @INC.
+Note that this file handle must be a real file handle (strictly a typeglob,
+or reference to a typeglob, blessed or unblessed) - tied file handles will be
+ignored and return value processing will stop there.
 
 If the hook is an array reference, its first element must be a subroutine
 reference.  This subroutine is called as above, but the first parameter is
@@ -4563,8 +4596,8 @@ or:
 
 If the hook is an object, it must provide an INC method that will be
 called as above, the first parameter being the object itself.  (Note that
-you must fully qualify the sub's name, as it is always forced into package
-C<main>.)  Here is a typical code layout:
+you must fully qualify the sub's name, as unqualified C<INC> is always forced
+into package C<main>.)  Here is a typical code layout:
 
     # In Foo.pm
     package Foo;