diff options
Diffstat (limited to 'upstream/archlinux/man3/PerlIO::via.3perl')
| -rw-r--r-- | upstream/archlinux/man3/PerlIO::via.3perl | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/PerlIO::via.3perl b/upstream/archlinux/man3/PerlIO::via.3perl new file mode 100644 index 00000000..fa0addc6 --- /dev/null +++ b/upstream/archlinux/man3/PerlIO::via.3perl @@ -0,0 +1,298 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PerlIO::via 3perl" +.TH PerlIO::via 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +PerlIO::via \- Helper class for PerlIO layers implemented in perl +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& use PerlIO::via::Layer; +\& open($fh,"<:via(Layer)",...); +\& +\& use Some::Other::Package; +\& open($fh,">:via(Some::Other::Package)",...); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The PerlIO::via module allows you to develop PerlIO layers in Perl, without +having to go into the nitty gritty of programming C with XS as the interface +to Perl. +.PP +One example module, PerlIO::via::QuotedPrint, is included with Perl +5.8.0, and more example modules are available from CPAN, such as +PerlIO::via::StripHTML and PerlIO::via::Base64. The +PerlIO::via::StripHTML module for instance, allows you to say: +.PP +.Vb 3 +\& use PerlIO::via::StripHTML; +\& open( my $fh, "<:via(StripHTML)", "index.html" ); +\& my @line = <$fh>; +.Ve +.PP +to obtain the text of an HTML-file in an array with all the HTML-tags +automagically removed. +.PP +Please note that if the layer is created in the PerlIO::via:: namespace, it +does \fBnot\fR have to be fully qualified. The PerlIO::via module will prefix +the PerlIO::via:: namespace if the specified modulename does not exist as a +fully qualified module name. +.SH "EXPECTED METHODS" +.IX Header "EXPECTED METHODS" +To create a Perl module that implements a PerlIO layer in Perl (as opposed to +in C using XS as the interface to Perl), you need to supply some of the +following subroutines. It is recommended to create these Perl modules in the +PerlIO::via:: namespace, so that they can easily be located on CPAN and use +the default namespace feature of the PerlIO::via module itself. +.PP +Please note that this is an area of recent development in Perl and that the +interface described here is therefore still subject to change (and hopefully +will have better documentation and more examples). +.PP +In the method descriptions below \fR\f(CI$fh\fR\fI\fR will be +a reference to a glob which can be treated as a perl file handle. +It refers to the layer below. \fI\fR\f(CI$fh\fR\fI\fR is not passed if the layer +is at the bottom of the stack, for this reason and to maintain +some level of "compatibility" with TIEHANDLE classes it is passed last. +.ie n .IP $class\->PUSHED([$mode,[$fh]]) 4 +.el .IP \f(CW$class\fR\->PUSHED([$mode,[$fh]]) 4 +.IX 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. +.Sp +When the layer is pushed as part of an \f(CW\*(C`open\*(C'\fR call, \f(CW\*(C`PUSHED\*(C'\fR will be called +\&\fIbefore\fR the actual open occurs, whether that be via \f(CW\*(C`OPEN\*(C'\fR, \f(CW\*(C`SYSOPEN\*(C'\fR, +\&\f(CW\*(C`FDOPEN\*(C'\fR or by letting a lower layer do the open. +.ie n .IP $obj\->POPPED([$fh]) 4 +.el .IP \f(CW$obj\fR\->POPPED([$fh]) 4 +.IX Item "$obj->POPPED([$fh])" +Optional \- called when the layer is about to be removed. +.ie n .IP $obj\->UTF8($belowFlag,[$fh]) 4 +.el .IP \f(CW$obj\fR\->UTF8($belowFlag,[$fh]) 4 +.IX Item "$obj->UTF8($belowFlag,[$fh])" +Optional \- if present it will be called immediately after PUSHED has +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 +.Sp +.Vb 1 +\& ":via(YourClass):utf8" +.Ve +.Sp +If not present or if it returns false, then the stream is left with +the UTF\-8 flag clear. +The \fR\f(CI$belowFlag\fR\fI\fR argument will be true if there is a layer below +and that layer was expecting UTF\-8. +.ie n .IP $obj\->OPEN($path,$mode,[$fh]) 4 +.el .IP \f(CW$obj\fR\->OPEN($path,$mode,[$fh]) 4 +.IX Item "$obj->OPEN($path,$mode,[$fh])" +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 a lower layer to do the open and then regain control. +.ie n .IP $obj\->BINMODE([$fh]) 4 +.el .IP \f(CW$obj\fR\->BINMODE([$fh]) 4 +.IX Item "$obj->BINMODE([$fh])" +Optional \- if not present the layer is popped on binmode($fh) or when \f(CW\*(C`:raw\*(C'\fR +is pushed. If present it should return 0 on success, \-1 on error, or undef +to pop the layer. +.ie n .IP $obj\->FDOPEN($fd,[$fh]) 4 +.el .IP \f(CW$obj\fR\->FDOPEN($fd,[$fh]) 4 +.IX Item "$obj->FDOPEN($fd,[$fh])" +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 a lower layer to do the open and then regain control. +.ie n .IP $obj\->SYSOPEN($path,$imode,$perm,[$fh]) 4 +.el .IP \f(CW$obj\fR\->SYSOPEN($path,$imode,$perm,[$fh]) 4 +.IX Item "$obj->SYSOPEN($path,$imode,$perm,[$fh])" +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 a lower layer to do the open and then regain control. +.ie n .IP $obj\->FILENO($fh) 4 +.el .IP \f(CW$obj\fR\->FILENO($fh) 4 +.IX Item "$obj->FILENO($fh)" +Returns a numeric value for a Unix-like file descriptor. Returns \-1 if +there isn't one. Optional. Default is fileno($fh). +.ie n .IP $obj\->READ($buffer,$len,$fh) 4 +.el .IP \f(CW$obj\fR\->READ($buffer,$len,$fh) 4 +.IX Item "$obj->READ($buffer,$len,$fh)" +Returns the number of octets placed in \f(CW$buffer\fR (must be less than or +equal to \f(CW$len\fR). Optional. Default is to use FILL instead. +.ie n .IP $obj\->WRITE($buffer,$fh) 4 +.el .IP \f(CW$obj\fR\->WRITE($buffer,$fh) 4 +.IX Item "$obj->WRITE($buffer,$fh)" +Returns the number of octets from \f(CW$buffer\fR that have been successfully written. +.ie n .IP $obj\->FILL($fh) 4 +.el .IP \f(CW$obj\fR\->FILL($fh) 4 +.IX 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 +PUSHED. +.ie n .IP $obj\->CLOSE($fh) 4 +.el .IP \f(CW$obj\fR\->CLOSE($fh) 4 +.IX Item "$obj->CLOSE($fh)" +Should return 0 on success, \-1 on error. +Optional. +.ie n .IP $obj\->SEEK($posn,$whence,$fh) 4 +.el .IP \f(CW$obj\fR\->SEEK($posn,$whence,$fh) 4 +.IX Item "$obj->SEEK($posn,$whence,$fh)" +Should return 0 on success, \-1 on error. +Optional. Default is to fail, but that is likely to be changed +in future. +.ie n .IP $obj\->TELL($fh) 4 +.el .IP \f(CW$obj\fR\->TELL($fh) 4 +.IX Item "$obj->TELL($fh)" +Returns file position. +Optional. Default to be determined. +.ie n .IP $obj\->UNREAD($buffer,$fh) 4 +.el .IP \f(CW$obj\fR\->UNREAD($buffer,$fh) 4 +.IX Item "$obj->UNREAD($buffer,$fh)" +Returns the number of octets from \f(CW$buffer\fR 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. +.ie n .IP $obj\->FLUSH($fh) 4 +.el .IP \f(CW$obj\fR\->FLUSH($fh) 4 +.IX Item "$obj->FLUSH($fh)" +Flush any buffered write data. May possibly be called on readable +handles too. Should return 0 on success, \-1 on error. +.ie n .IP $obj\->SETLINEBUF($fh) 4 +.el .IP \f(CW$obj\fR\->SETLINEBUF($fh) 4 +.IX Item "$obj->SETLINEBUF($fh)" +Optional. No return. +.ie n .IP $obj\->CLEARERR($fh) 4 +.el .IP \f(CW$obj\fR\->CLEARERR($fh) 4 +.IX Item "$obj->CLEARERR($fh)" +Optional. No return. +.ie n .IP $obj\->ERROR($fh) 4 +.el .IP \f(CW$obj\fR\->ERROR($fh) 4 +.IX Item "$obj->ERROR($fh)" +Optional. Returns error state. Default is no error until a mechanism +to signal error (die?) is worked out. +.ie n .IP $obj\->EOF($fh) 4 +.el .IP \f(CW$obj\fR\->EOF($fh) 4 +.IX Item "$obj->EOF($fh)" +Optional. Returns end-of-file state. Default is a function of the return +value of FILL or READ. +.SH EXAMPLES +.IX Header "EXAMPLES" +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, a simple example is included here. +.SS "Example \- a Hexadecimal Handle" +.IX Subsection "Example - a Hexadecimal Handle" +Given the following module, PerlIO::via::Hex : +.PP +.Vb 1 +\& package PerlIO::via::Hex; +\& +\& sub PUSHED +\& { +\& my ($class,$mode,$fh) = @_; +\& # When writing we buffer the data +\& my $buf = \*(Aq\*(Aq; +\& return bless \e$buf,$class; +\& } +\& +\& sub FILL +\& { +\& my ($obj,$fh) = @_; +\& my $line = <$fh>; +\& return (defined $line) ? pack("H*", $line) : undef; +\& } +\& +\& sub WRITE +\& { +\& my ($obj,$buf,$fh) = @_; +\& $$obj .= unpack("H*", $buf); +\& return length($buf); +\& } +\& +\& sub FLUSH +\& { +\& my ($obj,$fh) = @_; +\& print $fh $$obj or return \-1; +\& $$obj = \*(Aq\*(Aq; +\& return 0; +\& } +\& +\& 1; +.Ve +.PP +The following code opens up an output handle that will convert any +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") +.PP +.Vb 2 +\& use PerlIO::via::Hex; +\& open(my $fh, ">:via(Hex)", "foo.hex"); +.Ve +.PP +and the following code will read the hexdump in and convert it +on the fly back into bytes: +.PP +.Vb 1 +\& open(my $fh, "<:via(Hex)", "foo.hex"); +.Ve |