Extensive documentation patch redux

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

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 604da50..94c0e98 100644 (file)
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -324,7 +324,7 @@ to change during one "get".)
 
 =over 4
 
-=item size
+=item fsize
 
        Size_t fsize;
 
@@ -675,6 +675,51 @@ The application (or layer above) must ensure they are consistent.
 
 =back
 
+=head2 Implementing PerlIO Layers
+
+If you are creating a PerlIO layer, you may want to be lazy, in other
+words, implement only the methods that interest you.  The other methods
+you can either replace with the "blank" methods
+
+    PerlIOBase_noop_ok
+    PerlIOBase_noop_fail
+
+(which do nothing, and return zero and -1, respectively) or for
+certain methods you may assume a default behaviour by using a NULL
+method.  The Open method looks for help in the 'parent' layer.
+The following table summarizes the behaviour:
+
+    method      behaviour with NULL
+
+    Clearerr    PerlIOBase_clearerr
+    Close       PerlIOBase_close
+    Dup         PerlIOBase_dup
+    Eof         PerlIOBase_eof
+    Error       PerlIOBase_error
+    Fileno      PerlIOBase_fileno
+    Fill        FAILURE
+    Flush       SUCCESS
+    Getarg      SUCCESS
+    Get_base    FAILURE
+    Get_bufsiz  FAILURE
+    Get_cnt     FAILURE
+    Get_ptr     FAILURE
+    Open        INHERITED
+    Popped      SUCCESS
+    Pushed      SUCCESS
+    Read        PerlIOBase_read
+    Seek        FAILURE
+    Set_cnt     FAILURE
+    Set_ptrcnt  FAILURE
+    Setlinebuf  PerlIOBase_setlinebuf
+    Tell        FAILURE
+    Unread      PerlIOBase_unread
+    Write       FAILURE
+
+ FAILURE        Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and
+                return -1 (for numeric return values) or NULL (for pointers)
+ INHERITED      Inherited from the layer below
+ SUCCESS        Return 0 (for numeric return values) or a pointer 
 
 =head2 Core Layers
 
@@ -780,27 +825,31 @@ makes this layer available, although F<PerlIO.pm> "knows" where to
 find it.  It is an example of a layer which takes an argument as it is
 called thus:
 
-   open($fh,"<:encoding(iso-8859-7)",$pathname)
+   open( $fh, "<:encoding(iso-8859-7)", $pathname );
 
-=item ":Scalar"
+=item ":scalar"
 
-Provides support for
+Provides support for reading data from and writing data to a scalar.
 
-   open($fh,"...",\$scalar)
+   open( $fh, "+<:scalar", \$scalar );
 
 When a handle is so opened, then reads get bytes from the string value
 of I<$scalar>, and writes change the value. In both cases the position
 in I<$scalar> starts as zero but can be altered via C<seek>, and
 determined via C<tell>.
 
-=item ":Via"
+Please note that this layer is implied when calling open() thus:
+
+   open( $fh, "+<", \$scalar );
+
+=item ":via"
 
 Provided to allow layers to be implemented as Perl code.  For instance:
 
-   use MIME::QuotedPrint;
-   open(my $fh, ">Via(MIME::QuotedPrint)", "qp");
+   use PerlIO::via::StripHTML;
+   open( my $fh, "<:via(StripHTML)", "index.html" );
 
-See L<PerlIO::Via> for details.
+See L<PerlIO::via> for details.
 
 =back
 
@@ -867,6 +916,3 @@ a person who is not a PerlIO guru (yet).
 =back
 
 =cut
-
-
-