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