1transchan(n)                 Tcl Built-In Commands                transchan(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       transchan - command handler API of channel transforms
9

SYNOPSIS

11       cmdPrefix option ?arg arg ...?
12______________________________________________________________________________
13

DESCRIPTION

15       The  Tcl-level handler for a channel transformation has to be a command
16       with subcommands (termed an ensemble despite not implying that it  must
17       be  created  with namespace ensemble create; this mechanism is not tied
18       to namespace ensemble in any way). Note that cmdPrefix is whatever  was
19       specified  in  the call to chan push, and may consist of multiple argu‐
20       ments; this will be expanded to multiple words in place of the prefix.
21
22       Of all the possible subcommands, the handler  must  support  initialize
23       and  finalize.  Transformations for writable channels must also support
24       write, and transformations for  readable  channels  must  also  support
25       read.
26
27       Note  that  in  the  descriptions  below cmdPrefix may be more than one
28       word, and handle is the value returned by the chan push  call  used  to
29       create the transformation.
30
31   GENERIC SUBCOMMANDS
32       The following subcommands are relevant to all types of channel.
33
34       cmdPrefix clear handle
35              This optional subcommand is called to signify to the transforma‐
36              tion that any data stored in internal buffers  (either  incoming
37              or  outgoing)  must be cleared. It is called when a chan seek is
38              performed on the channel being transformed.
39
40       cmdPrefix finalize handle
41              This mandatory subcommand is called last for the  given  handle,
42              and then never again, and it exists to allow for cleaning up any
43              Tcl-level data structures associated  with  the  transformation.
44              Warning!  Any  errors thrown by this subcommand will be ignored.
45              It is not guaranteed to be called if the interpreter is deleted.
46
47       cmdPrefix initialize handle mode
48              This mandatory subcommand is called first, and then never  again
49              (for  the given handle). Its responsibility is to initialize all
50              parts of the transformation at the Tcl level. The mode is a list
51              containing any of read and write.
52
53              write  implies that the channel is writable.
54
55              read   implies that the channel is readable.
56
57              The  return  value of the subcommand should be a list containing
58              the names of all subcommands  supported  by  this  handler.  Any
59              error  thrown by the subcommand will prevent the creation of the
60              transformation. The thrown error will appear as error thrown  by
61              chan push.
62
63   READ-RELATED SUBCOMMANDS
64       These  subcommands  are  used  for  handling transformations applied to
65       readable channels; though strictly read is optional, it  must  be  sup‐
66       ported  if  any  of the others is or the channel will be made non-read‐
67       able.
68
69       cmdPrefix drain handle
70              This optional subcommand is called whenever data in  the  trans‐
71              formation input (i.e. read) buffer has to be forced upward, i.e.
72              towards the user or script.  The result returned by  the  method
73              is  taken  as  the binary data to push upward to the level above
74              this transformation (the reader or  a  higher-level  transforma‐
75              tion).
76
77              In  other  words,  when this method is called the transformation
78              cannot defer the actual transformation operation anymore and has
79              to  transform  all data waiting in its internal read buffers and
80              return the result of that action.
81
82       cmdPrefix limit? handle
83              This optional subcommand is called to allow the Tcl  I/O  engine
84              to determine how far ahead it should read. If present, it should
85              return an integer number greater than zero which  indicates  how
86              many bytes ahead should be read, or an integer less than zero to
87              indicate that the I/O engine may read as far ahead as it likes.
88
89       cmdPrefix read handle buffer
90              This subcommand, which must be present if the transformation  is
91              to  work  with  readable  channels,  is called whenever the base
92              channel, or a transformation below this  transformation,  pushes
93              data  upward. The buffer contains the binary data which has been
94              given to us from below. It is the responsibility of this subcom‐
95              mand  to actually transform the data. The result returned by the
96              subcommand is taken as the binary data to push further upward to
97              the  transformation  above this transformation. This can also be
98              the user or script that originally read from the channel.
99
100              Note that the result is allowed to be empty, or even  less  than
101              the  data  we  received;  the  transformation is not required to
102              transform everything given to it right now.  It  is  allowed  to
103              store  incoming data in internal buffers and to defer the actual
104              transformation until it has more data.
105
106   WRITE-RELATED SUBCOMMANDS
107       These subcommands are used  for  handling  transformations  applied  to
108       writable  channels;  though strictly write is optional, it must be sup‐
109       ported if any of the others  is  or  the  channel  will  be  made  non-
110       writable.
111
112       cmdPrefix flush handle
113              This  optional  subcommand is called whenever data in the trans‐
114              formation 'write' buffer has to be forced downward, i.e. towards
115              the base channel. The result returned by the subcommand is taken
116              as the binary data to write to the transformation below the cur‐
117              rent transformation. This can be the base channel as well.
118
119              In  other  words, when this subcommand is called the transforma‐
120              tion cannot defer the actual  transformation  operation  anymore
121              and has to transform all data waiting in its internal write buf‐
122              fers and return the result of that action.
123
124       cmdPrefix write handle buffer
125              This subcommand, which must be present if the transformation  is
126              to  work with writable channels, is called whenever the user, or
127              a transformation above this transformation,  writes  data  down‐
128              ward. The buffer contains the binary data which has been written
129              to us. It is the responsibility of this subcommand  to  actually
130              transform the data.
131
132              The  result  returned  by  the subcommand is taken as the binary
133              data to write to the transformation below  this  transformation.
134              This  can  be  the base channel as well. Note that the result is
135              allowed to be empty, or less than the data we got; the transfor‐
136              mation is not required to transform everything which was written
137              to it right now. It is allowed to store this  data  in  internal
138              buffers and to defer the actual transformation until it has more
139              data.
140

SEE ALSO

142       chan(n), refchan(n)
143

KEYWORDS

145       API, channel, ensemble, prefix, transformation
146
147
148
149Tcl                                   8.6                         transchan(n)
Impressum