This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add test for Pod::LaTeX; re-sort MANIFEST.
[perl5.git] / ext / PerlIO / Via / Via.pm
CommitLineData
e7a1fdd7
NIS
1package PerlIO::Via;
2our $VERSION = '0.01';
3use XSLoader ();
4XSLoader::load 'PerlIO::Via';
51;
6__END__
7
8=head1 NAME
9
10PerlIO::Via - Helper class for PerlIO layers implemented in perl
11
12=head1 SYNOPSIS
13
14 use Some::Package;
15
16 open($fh,"<:Via(Some::Package)",...);
17
18=head1 DESCRIPTION
19
20The package to be used as a layer should implement at least some of the
21following methods. In the method descriptions below I<$fh> will be
22a reference to a glob which can be treated as a perl file handle.
23It refers to the layer below. I<$fh> is not passed if the layer
24is at the bottom of the stack, for this reason and to maintain
2b8740d8
JH
25some level of "compatibility" with TIEHANDLE classes it is passed last.
26
27As an example, in Perl release 5.8.0 the MIME::QuotedPrint module
28defines the required TIEHANDLE methods so that you can say
29
30 use MIME::QuotedPrint;
31 open(my $fh, ">Via(MIME::QuotedPrint)", "qp");
e7a1fdd7
NIS
32
33=over 4
34
35=item $class->PUSHED([$mode][,$fh])
36
37Should return an object or the class. (Compare TIEHANDLE.)
38Mandatory.
39
40=item $obj->POPPED([$fh])
41
42Optional - layer is about to be removed.
43
44=item $class->OPEN($path,$mode[,$fh])
45
46Not yet in use.
47
48=item $class->FDOPEN($fd)
49
50Not yet in use.
51
52=item $class->SYSOPEN($path,$imode,$perm,$fh)
53
54Not yet in use.
55
56=item $obj->FILENO($fh)
57
47bfe92f
JH
58Returns a numeric value for Unix-like file descriptor. Return -1 if
59there isn't one. Optional. Default is fileno($fh).
e7a1fdd7
NIS
60
61=item $obj->READ($buffer,$len,$fh)
62
6391fff2
MJD
63Returns the number of octets placed in $buffer (must be less than or
64equal to $len). Optional. Default is to use FILL instead.
e7a1fdd7
NIS
65
66=item $obj->WRITE($buffer,$fh)
67
68Returns the number of octets from buffer that have been sucessfully written.
69
70=item $obj->FILL($fh)
71
47bfe92f
JH
72Should return a string to be placed in the buffer. Optional. If not
73provided must provide READ or reject handles open for reading in
74PUSHED.
e7a1fdd7
NIS
75
76=item $obj->CLOSE($fh)
77
78Should return 0 on success, -1 on error.
79Optional.
80
81=item $obj->SEEK($posn,$whence,$fh)
82
83Should return 0 on success, -1 on error.
84Optional. Default is to fail, but that is likely to be changed.
85
86=item $obj->TELL($fh)
87
88Returns file postion.
89Optional. Default to be determined.
90
91=item $obj->UNREAD($buffer,$fh)
92
47bfe92f
JH
93Returns the number of octets from buffer that have been sucessfully
94saved to be returned on future FILL/READ calls. Optional. Default is
95to push data into a temporary layer above this one.
e7a1fdd7
NIS
96
97=item $obj->FLUSH($fh)
98
47bfe92f
JH
99Flush any buffered write data. May possibly be called on readable
100handles too. Should return 0 on success, -1 on error.
e7a1fdd7
NIS
101
102=item $obj->SETLINEBUF($fh)
103
104Optional. No return.
105
106=item $obj->CLEARERR($fh)
107
108Optional. No return.
109
110=item $obj->ERROR($fh)
111
112Optional. Returns error state. Default is no error until a mechanism
113to signal error (die?) is worked out.
114
115=item $obj->EOF($fh)
116
47bfe92f
JH
117Optional. Returns end-of-file state. Default is function of return
118value of FILL or READ.
e7a1fdd7
NIS
119
120=back
121
122=cut
123
124