Trf: The transform command
Author: Andreas Kupries,,,

# Trf commands: transform

[ Misc commands | Sitemap ]

Options understood by ``transform''are:

-mode | Allowed arguments are ``read'', ``write'' and all unique abbreviations of these. This option is relevant and required only for immediate operation. It determines the operations to execute.
-command | Its specification is always required, and interpreted as the script to execute on behalf of the channel filter. The system will append two arguments to the script before execution, the name of the operation and a buffer to operate on.

The operations and their meaning are:

Operation | Meaning
create/write | Initialize state of transformation for writing into channel. The buffer is irrelevant, and empty. A return value is ignored. First call for writing part.
delete/write | Cleanup state of transformation for writing into channel. The buffer is irrelevant, and empty. A return value is ignored. Last call for writing part.
write | Execute write transformation on the given buffer. The return value is interpreted as transformation result.
flush/write | Flush out all buffers internal to the transformation. The given buffer is empty. The return value is interpreted as transformation result.
clear/write | Cleanup state of transformation for writing into channel. The buffer is irrelevant, and empty. A return value is ignored.
create/read | Initialize state of transformation for read from channel. The buffer is irrelevant, and empty. A return value is ignored. First call for reading part.
delete/read | Cleanup state of transformation for read from channel. The buffer is irrelevant, and empty. A return value is ignored. Last call for reading part.
read | Execute read transformation on the given buffer. The return value is interpreted as transformation result. Normally the inverse of the write transformation.
flush/read | Flush out all buffers internal to the transformation. The given buffer is empty. The return value is interpreted as transformation result. Required to get buffered partial results at EOF of the underlying channel.
clear/read | Cleanup state of transformation for read from channel. The buffer is irrelevant, and empty. A return value is ignored. Called during seeks on the channel.
query/maxRead | The transformation is queried for the maximum number of bytes to read. This call is done just before reading more data from the underlying. The return value has to be an integer number. A negative value signal acceptance of whatever number of characters the trf layer decides to read.
query/ratio | The transformation is queried for its natural seek ratio. Called once after the creation of the transformation (and its attachment to a channel). The return value has to be a list containing at least 2 elements. The first two elements of the list are interpreted as the natural ratio of the transformation.

Using this command under `tcl` 7.6 will yield incorrect results if the buffer to be transformed contains embbeded \0's.

Last update at Mon Aug 20 22:52:27 PDT 2001