1[include common/trf_version.inc]
2[manpage_begin transform n [vset trf_version]]
3[titledesc "Tcl level transformations"]
4[include common/trf_header.inc]
5[description]
6
7The command [cmd transform] reflects the API for a stack channel
8transformation into the tcl level, thus enabling the writing of
9transformations in tcl.
10
11[para]
12[list_begin definitions]
13
14[call [cmd transform] [opt [arg options...]] [opt [arg data]]]
15
16[list_begin definitions]
17
18[lst_item "[option -mode] [const read]|[const write]"]
19
20This option is accepted by the command if and only if it is used in
21[term immediate] mode.  See section
22[sectref {IMMEDIATE versus ATTACHED}] for an explanation of the term.
23
24[nl]
25
26The argument value specifies whether to run the read or the write part
27of the transformation specified via option [option -command] on the
28immediate data.
29
30[nl]
31
32Beyond the argument values listed above all unique abbreviations are
33recognized too.
34
35
36[lst_item "[option -command] [arg cmd]"]
37
38This option has to be present and is always understood. Its argument
39is a command prefix. This command prefix will be called by internally
40whenever some operation of the transformation has to be executed. An
41empty [arg cmd] is not allowed.
42
43[nl]
44
45The exact nature of the various possible calls and their expected
46results is described later, in section [sectref {CALLBACK API}].
47
48
49[include common/options.inc]
50[list_end]
51[list_end]
52
53[include common/sections.inc]
54
55[section {CALLBACK API}]
56
57Here we describe the API of the callback command implementing the
58actual transformation.
59
60[para]
61
62[list_begin definitions]
63[call [cmd callback] [arg operation] [arg data]]
64
65The callback is always called with two arguments, first an operation
66code followed by data. The latter will be empty for some operations.
67
68[nl]
69
70The known operations are listed below, together with an explanation of
71the arguments, what is expected of them, and how their results are
72handled.
73
74[list_begin definitions]
75
76[lst_item [const create/write]]
77
78When called [arg data] is empty. The result of the call is ignored.
79
80[nl]
81
82This is the first operation executed for the write side of the
83transformation. It has to initialize the internals of this part of the
84transformation and ready it for future calls.
85
86
87[lst_item [const delete/write]]
88
89When called [arg data] is empty. The result of the call is ignored.
90
91[nl]
92
93This is the last operation executed for the write side of the
94transformation. It has to shutdown the internals of this part of the
95transformation and release any resources which were acquired over the
96lifetime of the transformation.
97
98
99[lst_item [const write]]
100
101The operation is called whenever data is written to the channel.
102
103[nl]
104
105At the time of the call the argument [arg data] will contain the bytes
106to transform. The result of the call is taken as the result of the
107transformation and handed to the next stage down in the stack of
108transformation associated with the channel.
109
110[nl]
111
112This operation has to transform the contents of [arg data], using
113whatever data was left over from the last call of the operation. The
114transformation is allowed to buffer incomplete data.
115
116
117[lst_item [const flush/write]]
118
119When called [arg data] is empty. The operation has to transform any
120incomplete data it has buffered internally on the write side. The
121result of the call is taken as the result of the transformation and
122handed to the next stage down in the stack of transformation
123associated with the channel.
124
125
126[lst_item [const clear/write]]
127
128When called [arg data] is empty. The result of the call is ignored.
129
130[nl]
131
132The write side of the transformation has to clear its internal
133buffers. This operation is called when the user seeks on the channel,
134thus invalidating any incomplete transformation.
135
136
137[lst_item [const create/read]]
138
139When called [arg data] is empty. The result of the call is ignored.
140
141[nl]
142
143This is the first operation executed for the read side of the
144transformation. It has to initialize the internals of this part of the
145transformation and ready it for future calls.
146
147
148[lst_item [const delete/read]]
149
150When called [arg data] is empty. The result of the call is ignored.
151
152[nl]
153
154This is the last operation executed for the write side of the
155transformation. It has to shutdown the internals of this part of the
156transformation and release any resources which were acquired over the
157lifetime of the transformation.
158
159
160[lst_item [const read]]
161
162The operation is called whenever data is read from the channel.
163
164[nl]
165
166At the time of the call the argument [arg data] will contain the bytes
167to transform. The result of the call is taken as the result of the
168transformation and posted to the next stage up in the stack of
169transformation associated with the channel.
170
171[nl]
172
173This operation has to transform the contents of [arg data], using
174whatever data was left over from the last call of the operation. The
175transformation is allowed to buffer incomplete data.
176
177
178
179[lst_item [const flush/read]]
180
181When called [arg data] is empty. The operation has to transform any
182incomplete data it has buffered internally on the read side. The
183result of the call is taken as the result of the transformation and
184posted to the next stage up in the stack of transformation associated
185with the channel.
186
187
188[lst_item [const clear/read]]
189
190When called [arg data] is empty. The result of the call is ignored.
191
192[nl]
193
194The read side of the transformation has to clear its internal
195buffers. This operation is called when the user seeks on the channel,
196thus invalidating any incomplete transformation.
197
198
199[lst_item [const query/maxRead]]
200
201When called [arg data] is empty. The result of the call is interpreted
202as integer number. This operation is used by the generic layer to
203determine if the transformation establishes a limit on the number of
204bytes it (the generic layer) is allowed read from the transformations
205lower in the stack. A negative result unsets any limit.
206
207[nl]
208
209This has to be used if a transformation employs some kind of
210end-of-data marker. We cannot allow the generic layer to overshoot
211this marker because any data read after it cannot be stuffed back into
212the core buffers, causing the I/O system to loose data if the
213transformation is unstacked after it recognized the end of its
214data. This is a limitation of the I/O system in the tcl core.
215
216[nl]
217
218Returning a positive value will cause the I/O system to slow down, but
219also ensures that no data is lost.
220
221[nl]
222
223Two examples for such transformations are the data decompressors for
224[cmd zip] and [cmd bz2]. They use the C-level equivalent of this
225operation to prevent the overshooting.
226
227[list_end]
228[list_end]
229
230[see_also  trf-intro]
231[keywords {general transform}]
232[manpage_end]
233