From: Lanning, Scott Date: Sun, 25 Jan 2009 17:55:25 +0000 (+0100) Subject: Some POD patches for PerlIO and PerlIO::var X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9ec269cbd74dc9e148af091390dea461a8770d2e;p=p5sagit%2Fp5-mst-13.2.git Some POD patches for PerlIO and PerlIO::var Mostly just grammar. --- diff --git a/ext/PerlIO/via/via.pm b/ext/PerlIO/via/via.pm index 6ff804e..66aa974 100644 --- a/ext/PerlIO/via/via.pm +++ b/ext/PerlIO/via/via.pm @@ -60,66 +60,65 @@ some level of "compatibility" with TIEHANDLE classes it is passed last. =over 4 -=item $class->PUSHED([$mode[,$fh]]) +=item $class->PUSHED([$mode,[$fh]]) Should return an object or the class, or -1 on failure. (Compare TIEHANDLE.) The arguments are an optional mode string ("r", "w", "w+", ...) and a filehandle for the PerlIO layer below. Mandatory. -When layer is pushed as part of an C call, C will be called -I the actual open occurs whether than be via C, C, -C or by letting lower layer do the open. +When the layer is pushed as part of an C call, C will be called +I the actual open occurs, whether that be via C, C, +C or by letting a lower layer do the open. =item $obj->POPPED([$fh]) -Optional - layer is about to be removed. +Optional - called when the layer is about to be removed. =item $obj->UTF8($bellowFlag,[$fh]) Optional - if present it will be called immediately after PUSHED has -returned. It should return true value if the layer expects data to be -UTF-8 encoded. If it returns true result is as if caller had done +returned. It should return a true value if the layer expects data to be +UTF-8 encoded. If it returns true, the result is as if the caller had done ":via(YourClass):utf8" -If not present of it it returns false, then stream is left with -flag clear. +If not present or if it returns false, then the stream is left with +the UTF-8 flag clear. The I<$bellowFlag> argument will be true if there is a layer below and that layer was expecting UTF-8. +=item $obj->OPEN($path,$mode,[$fh]) -=item $obj->OPEN($path,$mode[,$fh]) - -Optional - if not present lower layer does open. -If present called for normal opens after layer is pushed. +Optional - if not present a lower layer does the open. +If present, called for normal opens after the layer is pushed. This function is subject to change as there is no easy way -to get lower layer to do open and then regain control. +to get a lower layer to do the open and then regain control. -=item $obj->BINMODE([,$fh]) +=item $obj->BINMODE([$fh]) -Optional - if not available layer is popped on binmode($fh) or when C<:raw> -is pushed. If present it should return 0 on success -1 on error and undef +Optional - if not present the layer is popped on binmode($fh) or when C<:raw> +is pushed. If present it should return 0 on success, -1 on error, or undef to pop the layer. -=item $obj->FDOPEN($fd[,$fh]) +=item $obj->FDOPEN($fd,[$fh]) -Optional - if not present lower layer does open. -If present called for opens which pass a numeric file -descriptor after layer is pushed. +Optional - if not present a lower layer does the open. +If present, called after the layer is pushed for opens which pass +a numeric file descriptor. This function is subject to change as there is no easy way -to get lower layer to do open and then regain control. +to get a lower layer to do the open and then regain control. -=item $obj->SYSOPEN($path,$imode,$perm,[,$fh]) +=item $obj->SYSOPEN($path,$imode,$perm,[$fh]) -Optional - if not present lower layer does open. -If present called for sysopen style opens which pass a numeric mode -and permissions after layer is pushed. +Optional - if not present a lower layer does the open. +If present, called after the layer is pushed for sysopen style opens +which pass a numeric mode and permissions. This function is subject to change as there is no easy way -to get lower layer to do open and then regain control. +to get a lower layer to do the open and then regain control. =item $obj->FILENO($fh) -Returns a numeric value for Unix-like file descriptor. Return -1 if +Returns a numeric value for a Unix-like file descriptor. Returns -1 if there isn't one. Optional. Default is fileno($fh). =item $obj->READ($buffer,$len,$fh) @@ -129,12 +128,12 @@ equal to $len). Optional. Default is to use FILL instead. =item $obj->WRITE($buffer,$fh) -Returns the number of octets from buffer that have been successfully written. +Returns the number of octets from $buffer that have been successfully written. =item $obj->FILL($fh) Should return a string to be placed in the buffer. Optional. If not -provided must provide READ or reject handles open for reading in +provided, must provide READ or reject handles open for reading in PUSHED. =item $obj->CLOSE($fh) @@ -155,7 +154,7 @@ Optional. Default to be determined. =item $obj->UNREAD($buffer,$fh) -Returns the number of octets from buffer that have been successfully +Returns the number of octets from $buffer that have been successfully saved to be returned on future FILL/READ calls. Optional. Default is to push data into a temporary layer above this one. @@ -179,7 +178,7 @@ to signal error (die?) is worked out. =item $obj->EOF($fh) -Optional. Returns end-of-file state. Default is function of return +Optional. Returns end-of-file state. Default is a function of the return value of FILL or READ. =back @@ -188,7 +187,7 @@ value of FILL or READ. Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers implemented in Perl. To give you an idea how simple the implementation of -a PerlIO layer can look, as simple example is included here. +a PerlIO layer can look, a simple example is included here. =head2 Example - a Hexadecimal Handle @@ -229,7 +228,7 @@ Given the following module, PerlIO::via::Hex : 1; The following code opens up an output handle that will convert any -output to hexadecimal dump of the output bytes: for example "A" will +output to a hexadecimal dump of the output bytes: for example "A" will be converted to "41" (on ASCII-based machines, on EBCDIC platforms the "A" will become "c1") diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index 1b80507..980df2c 100644 --- a/lib/PerlIO.pm +++ b/lib/PerlIO.pm @@ -71,7 +71,7 @@ UNIX/POSIX numeric file descriptor calls Layer which calls C, C and C/C etc. Note that as this is "real" stdio it will ignore any layers beneath it and -got straight to the operating system via the C library as usual. +go straight to the operating system via the C library as usual. =item :perlio @@ -108,16 +108,16 @@ Based on the C<:perlio> layer. =item :mmap A layer which implements "reading" of files by using C to -make (whole) file appear in the process's address space, and then +make a (whole) file appear in the process's address space, and then using that as PerlIO's "buffer". This I be faster in certain circumstances for large files, and may result in less physical memory use when multiple processes are reading the same file. Files which are not C-able revert to behaving like the C<:perlio> -layer. Writes also behave like C<:perlio> layer as C for write +layer. Writes also behave like the C<:perlio> layer, as C for write needs extra house-keeping (to extend the file) which negates any advantage. -The C<:mmap> layer will not exist if platform does not support C. +The C<:mmap> layer will not exist if the platform does not support C. =item :utf8 @@ -140,38 +140,38 @@ and then read it back in. close(F); Note that this layer does not validate byte sequences. For reading -input, using C<:encoding(utf8)> instead of bare C<:utf8>, is strongly +input, using C<:encoding(utf8)> instead of bare C<:utf8> is strongly recommended. =item :bytes -This is the inverse of C<:utf8> layer. It turns off the flag +This is the inverse of the C<:utf8> layer. It turns off the flag on the layer below so that data read from it is considered to -be "octets" i.e. characters in range 0..255 only. Likewise +be "octets" i.e. characters in the range 0..255 only. Likewise on output perl will warn if a "wide" character is written to a such a stream. =item :raw The C<:raw> layer is I as being identical to calling -C - the stream is made suitable for passing binary data +C - the stream is made suitable for passing binary data, i.e. each byte is passed as-is. The stream will still be buffered. In Perl 5.6 and some books the C<:raw> layer (previously sometimes also referred to as a "discipline") is documented as the inverse of the C<:crlf> layer. That is no longer the case - other layers which would -alter binary nature of the stream are also disabled. If you want UNIX +alter the binary nature of the stream are also disabled. If you want UNIX line endings on a platform that normally does CRLF translation, but still -want UTF-8 or encoding defaults the appropriate thing to do is to add -C<:perlio> to PERLIO environment variable. +want UTF-8 or encoding defaults, the appropriate thing to do is to add +C<:perlio> to the PERLIO environment variable. The implementation of C<:raw> is as a pseudo-layer which when "pushed" pops itself and then any layers which do not declare themselves as suitable for binary data. (Undoing :utf8 and :crlf are implemented by clearing flags rather than popping layers but that is an implementation detail.) -As a consequence of the fact that C<:raw> normally pops layers +As a consequence of the fact that C<:raw> normally pops layers, it usually only makes sense to have it as the only or first element in a layer specification. When used as the first element it provides a known base on which to build e.g. @@ -198,8 +198,8 @@ A more elegant (and safer) interface is needed. =item :win32 -On Win32 platforms this I layer uses native "handle" IO -rather than unix-like numeric file descriptor layer. Known to be +On Win32 platforms this I layer uses the native "handle" IO +rather than the unix-like numeric file descriptor layer. Known to be buggy as of perl 5.8.2. =back @@ -215,7 +215,7 @@ in Perl using the latter) come with the Perl distribution. =item :encoding Use C<:encoding(ENCODING)> either in open() or binmode() to install -a layer that does transparently character set and encoding transformations, +a layer that transparently does character set and encoding transformations, for example from Shift-JIS to Unicode. Note that under C an C<:encoding> also enables C<:utf8>. See L for more information. @@ -236,10 +236,10 @@ To get a binary stream an alternate method is to use: open($fh,"whatever") binmode($fh); -this has advantage of being backward compatible with how such things have +this has the advantage of being backward compatible with how such things have had to be coded on some platforms for years. -To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>) +To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>) in the open call: open($fh,"<:unix",$path) @@ -254,7 +254,7 @@ translation for text files then the default layers are : (The low level "unix" layer may be replaced by a platform specific low level layer.) -Otherwise if C found out how to do "fast" IO using system's +Otherwise if C found out how to do "fast" IO using the system's stdio, then the default layers are: unix stdio @@ -275,7 +275,7 @@ This can be used to see the effect of/bugs in the various layers e.g. PERLIO=stdio ./perl harness PERLIO=perlio ./perl harness -For the various value of PERLIO see L. +For the various values of PERLIO see L. =head2 Querying the layers of filehandles @@ -289,7 +289,7 @@ system and on the Perl version, and both the compile-time and runtime configurations of Perl. The following table summarizes the default layers on UNIX-like and -DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>: +DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>: PERLIO UNIX-like DOS-like ------ --------- -------- @@ -301,8 +301,8 @@ DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>: # [1] "stdio" if Configure found out how to do "fast stdio" (depends # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio" -By default the layers from the input side of the filehandle is -returned, to get the output side use the optional C argument: +By default the layers from the input side of the filehandle are +returned; to get the output side, use the optional C argument: my @layers = PerlIO::get_layers($fh, output => 1); @@ -318,10 +318,10 @@ You are supposed to use open() and binmode() to manipulate the stack. B -The arguments to layers are by default returned in parenthesis after +The arguments to layers are by default returned in parentheses after the name of the layer, and certain layers (like C) are not real -layers but instead flags on real layers: to get all of these returned -separately use the optional C
argument: +layers but instead flags on real layers; to get all of these returned +separately, use the optional C
argument: my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);