NAME

PerlIO::Via - Helper class for PerlIO layers implemented in perl

SYNOPSIS

   use Some::Package;

   open($fh,"<:Via(Some::Package)",...);

DESCRIPTION

The package to be used as a layer should implement at least some of the following methods. In the method descriptions below $fh will be a reference to a glob which can be treated as a perl file handle. It refers to the layer below. $fh 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.

$class->PUSHED([$mode][,$fh])

Should return an object or the class. (Compare TIEHANDLE.) Mandatory.

$obj->POPPED([$fh])

Optional - layer is about to be removed.

$class->OPEN($path,$mode[,$fh])

Not yet in use.

$class->FDOPEN($fd)

Not yet in use.

$class->SYSOPEN($path,$imode,$perm,$fh)

Not yet in use.

$obj->FILENO($fh)

Returns a numeric value for Unix-like file descriptor. Return -1 if there isn't one. Optional -default is fileno($fh).

$obj->READ($buffer,$len,$fh)

Returns the number of octets placed in $buffer (must be less that $len). Optional - default is to use FILL instead.

$obj->WRITE($buffer,$fh)

Returns the number of octets from buffer that have been sucessfully written.

$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.

$obj->CLOSE($fh)

Should return 0 on success, -1 on error. Optional.

$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.

$obj->TELL($fh)

Returns file postion. Optional. Default to be determined.

$obj->UNREAD($buffer,$fh)

Returns the number of octets from buffer that have been sucessfully saved to be returned on future FILL/READ calls. Optional. Default is to push data into a temporary layer above this one.

$obj->FLUSH($fh)

Flush any buffered write data. May possibly be called on readable handles too. Should return 0 on success, -1 on error.

$obj->SETLINEBUF($fh)

Optional. No return.

$obj->CLEARERR($fh)

Optional. No return.

$obj->ERROR($fh)

Optional. Returns error state. Default is no error until a mechanism to signal error (die?) is worked out.

$obj->EOF($fh)

Optional. Returns end-of-file state. Default is function of return value of FILL or READ.