This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Redundant return.
[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
a2ae6f84
JH
122=head2 Example - a Hexadecimal Handle
123
124Given the following module, Hex.pm:
125
126 package Hex;
127
128 sub PUSHED
129 {
130 my ($class,$mode) = @_;
131 # When writing we buffer the data
132 my $write = '';
133 return bless \$write,$class;
134 }
135
136 sub FILL
137 {
138 my ($obj,$fh) = @_;
139 my $line = <$fh>;
140 return (defined $line) ? pack("H*", $line) : undef;
141 return undef;
142 }
143
144 sub WRITE
145 {
146 my ($obj,$buf,$fh) = @_;
147 $$obj .= unpack("H*", $buf);
148 return length($buf);
149 }
150
151 sub FLUSH
152 {
153 my ($obj,$fh) = @_;
154 print $fh $$obj or return -1;
155 $$obj = '';
156 return 0;
157 }
158
159 1;
160
161the following code opens up an output handle that will convert any
162output to hexadecimal dump of the output bytes: for example "A" will
163be converted to "41" (on ASCII-based machines, on EBCDIC platforms
164the "A" will become "c1")
165
166 use Hex;
167 open(my $fh, ">:Via(Hex)", "foo.hex");
168
169and the following code will read the hexdump in and convert it
170on the fly back into bytes:
171
172 open(my $fh, "<:Via(Hex)", "foo.hex");
173
e7a1fdd7
NIS
174=cut
175
176