diff options
Diffstat (limited to 'doc/transchan.n')
-rw-r--r-- | doc/transchan.n | 160 |
1 files changed, 0 insertions, 160 deletions
diff --git a/doc/transchan.n b/doc/transchan.n deleted file mode 100644 index e308e13..0000000 --- a/doc/transchan.n +++ /dev/null @@ -1,160 +0,0 @@ -'\" -'\" Copyright (c) 2008 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.so man.macros -.TH transchan n 8.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -transchan \- command handler API of channel transforms -.SH SYNOPSIS -\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The Tcl-level handler for a channel transformation has to be a command with -subcommands (termed an \fIensemble\fR despite not implying that it must be -created with \fBnamespace ensemble create\fR; this mechanism is not tied to -\fBnamespace ensemble\fR in any way). Note that \fIcmdPrefix\fR is whatever -was specified in the call to \fBchan push\fR, and may consist of multiple -arguments; this will be expanded to multiple words in place of the prefix. -.PP -Of all the possible subcommands, the handler \fImust\fR support -\fBinitialize\fR and \fBfinalize\fR. Transformations for writable channels -must also support \fBwrite\fR, and transformations for readable channels must -also support \fBread\fR. -.PP -Note that in the descriptions below \fIcmdPrefix\fR may be more than one word, -and \fIhandle\fR is the value returned by the \fBchan push\fR call used to -create the transformation. -.SS "GENERIC SUBCOMMANDS" -.PP -The following subcommands are relevant to all types of channel. -.TP -\fIcmdPrefix \fBclear \fIhandle\fR -. -This optional subcommand is called to signify to the transformation that any -data stored in internal buffers (either incoming or outgoing) must be -cleared. It is called when a \fBchan seek\fR is performed on the channel being -transformed. -.TP -\fIcmdPrefix \fBfinalize \fIhandle\fR -. -This mandatory subcommand is called last for the given \fIhandle\fR, and then -never again, and it exists to allow for cleaning up any Tcl-level data -structures associated with the transformation. \fIWarning!\fR Any errors -thrown by this subcommand will be ignored. It is not guaranteed to be called -if the interpreter is deleted. -.TP -\fIcmdPrefix \fBinitialize \fIhandle mode\fR -. -This mandatory subcommand is called first, and then never again (for the given -\fIhandle\fR). Its responsibility is to initialize all parts of the -transformation at the Tcl level. The \fImode\fR is a list containing any of -\fBread \fRand \fBwrite\fR. -.RS -.TP -\fBwrite\fR -. -implies that the channel is writable. -.TP -\fBread\fR -. -implies that the channel is readable. -.PP -The return value of the subcommand should be a list containing the names of -all subcommands supported by this handler. Any error thrown by the subcommand -will prevent the creation of the transformation. The thrown error will appear -as error thrown by \fBchan push\fR. -.RE -.SS "READ-RELATED SUBCOMMANDS" -.PP -These subcommands are used for handling transformations applied to readable -channels; though strictly \fBread \fRis optional, it must be supported if any -of the others is or the channel will be made non-readable. -.TP -\fIcmdPrefix \fBdrain \fIhandle\fR -. -This optional subcommand is called whenever data in the transformation input -(i.e. read) buffer has to be forced upward, i.e. towards the user or script. -The result returned by the method is taken as the \fIbinary\fR data to push -upward to the level above this transformation (the reader or a higher-level -transformation). -.RS -.PP -In other words, when this method is called the transformation cannot defer the -actual transformation operation anymore and has to transform all data waiting -in its internal read buffers and return the result of that action. -.RE -.TP -\fIcmdPrefix \fBlimit? \fIhandle\fR -. -This optional subcommand is called to allow the Tcl I/O engine to determine -how far ahead it should read. If present, it should return an integer number -greater than zero which indicates how many bytes ahead should be read, or an -integer less than zero to indicate that the I/O engine may read as far ahead -as it likes. -.TP -\fIcmdPrefix \fBread \fIhandle buffer\fR -. -This subcommand, which must be present if the transformation is to work with -readable channels, is called whenever the base channel, or a transformation -below this transformation, pushes data upward. The \fIbuffer\fR contains the -binary data which has been given to us from below. It is the responsibility of -this subcommand to actually transform the data. The result returned by the -subcommand is taken as the binary data to push further upward to the -transformation above this transformation. This can also be the user or script -that originally read from the channel. -.RS -.PP -Note that the result is allowed to be empty, or even less than the data we -received; the transformation is not required to transform everything given to -it right now. It is allowed to store incoming data in internal buffers and to -defer the actual transformation until it has more data. -.RE -.SS "WRITE-RELATED SUBCOMMANDS" -.PP -These subcommands are used for handling transformations applied to writable -channels; though strictly \fBwrite\fR is optional, it must be supported if any -of the others is or the channel will be made non-writable. -.TP -\fIcmdPrefix \fBflush \fIhandle\fR -. -This optional subcommand is called whenever data in the transformation 'write' -buffer has to be forced downward, i.e. towards the base channel. The result -returned by the subcommand is taken as the binary data to write to the -transformation below the current transformation. This can be the base channel -as well. -.RS -.PP -In other words, when this subcommand is called the transformation cannot defer -the actual transformation operation anymore and has to transform all data -waiting in its internal write buffers and return the result of that action. -.RE -.TP -\fIcmdPrefix \fBwrite \fIhandle buffer\fR -. -This subcommand, which must be present if the transformation is to work with -writable channels, is called whenever the user, or a transformation above this -transformation, writes data downward. The \fIbuffer\fR contains the binary -data which has been written to us. It is the responsibility of this subcommand -to actually transform the data. -.RS -.PP -The result returned by the subcommand is taken as the binary data to write to -the transformation below this transformation. This can be the base channel as -well. Note that the result is allowed to be empty, or less than the data we -got; the transformation is not required to transform everything which was -written to it right now. It is allowed to store this data in internal buffers -and to defer the actual transformation until it has more data. -.RE -.SH "SEE ALSO" -chan(n), refchan(n) -.SH KEYWORDS -API, channel, ensemble, prefix, transformation -'\" Local Variables: -'\" mode: nroff -'\" End: |