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