1transfer::copy(n) Data transfer facilities transfer::copy(n)
2______________________________________________________________________________
6
8 transfer::copy - Data transfer foundation
9
11 package require Tcl 8.4
12 package require transfer::copy ?0.2?
14 transfer::copy::do chan|string data outchannel ?options...?
16 transfer::copy::chan channel outchannel ?options...?
18 transfer::copy::string string outchannel ?options...?
20 transfer::copy::doChan channel outchannel optvar
22 transfer::copy::doString string outchannel optvar
24 transfer::copy::options outchannel optionlist optvar
26______________________________________________________________________________
28
30 This package provides a number of commands for the asynchronous of
31 information contained in either a string or channel. The main point of
32 this package is that the commands here provide a nicer callback API
33 than the builtin command fcopy, making the use of these facilities sim‐
34 pler than the builtin.
35
37 transfer::copy::do chan|string data outchannel ?options...?
38 This command transfers the information in data to the outchan‐
39 nel, according to the options. The type of the information in
40 data is determined by the first argument.
41 The options available to this command are the same as are avail‐
43 able to the command transfer::copy::options, and explained
44 there.
45 chan The argument data contains the handle of a channel and
47 the actual infomration to transfer is read from that
48 channel.
49 string The argument data contains a string and this is the
51 information to be transfered.
52 transfer::copy::chan channel outchannel ?options...?
54 This command is a shorter and more direct form for the command
55 transfer::copy::do chan.
56 transfer::copy::string string outchannel ?options...?
58 This command is a shorter and more direct form for the command
59 transfer::copy::do string.
60 transfer::copy::doChan channel outchannel optvar
62 This command is an alternate form of transfer::copy::chan which
63 reads its options out of the array variable named by optvar
64 instead of from a variable length argument list.
65 transfer::copy::doString string outchannel optvar
67 This command is an alternate form of transfer::copy::string
68 which reads its options out of the array variable named by opt‐
69 var instead of from a variable length argument list.
70 transfer::copy::options outchannel optionlist optvar
72 This command is the option processor used by all the commands
73 above which read their options from a variable length argument
74 list. It first reads default settings from the channel handle
75 outchannel, then processes the list of options in optionlist, at
76 last stores the results in the array variable named by optvar.
77 The contents of that variable are in a format which is directly
78 understood by all the commands above which read their options
79 out of an array variable.
80 The recognized options are:
82 -blocksize int
84 This option specifies the size of the chunks to transfer
85 in one operation. It is optional and defaults to the
86 value of -buffersize as configured for the output chan‐
87 nel.
88 If specified its value has to be an integer number
90 greater than zero.
91 -command commandprefix
93 This option specifies the completion callback of the
94 operation. This option has to be specified. An error will
95 be thrown if it is not, or if the empty list was speci‐
96 fied as argument to it.
97 Its value has to be a command prefix, i.e. a list whose
99 first word is the command to execute, followed by words
100 containing fixed arguments. When the callback is invoked
101 one or two additional arguments are appended to the pre‐
102 fix. The first argument is the number of bytes which were
103 transfered. The optional second argument is an error mes‐
104 sage and added if and only if an error occured during the
105 the transfer.
106 -progress commandprefix
108 This option specifies the progress callback of the opera‐
109 tion. It is optional and defaults to the empty list. This
110 last possibility signals that no feedback was asked for
111 and disabled it.
112 Its value has to be a command prefix, see above, -command
114 for a more detailed explanation. When the callback is
115 invoked a single additional arguments is appended to the
116 prefix. This argument is the number of bytes which were
117 transfered so far.
118 -size int
120 This option specifies the number of bytes to read from
121 the input data and transfer. It is optional and defaults
122 to "Transfer everything". Its value has to be an integer
123 number and any value less than zero has the same meaning,
124 i.e. to transfer all available data. Any other value is
125 the amount of bytes to transfer.
126 All transfer commands will throw error an when their user
128 tries to transfer more data than is available in the
129 input. This happens immediately, before the transfer is
130 actually started, should the input be a string. Otherwise
131 the, i.e. for a channel as input, the error is thrown the
132 moment the underflow condition is actually detected.
133 -encoding encodingname
135 -eofchar eofspec
137 -translation transspec
139 These options are the same as are recognized by the
140 builtin command fconfigure and provide the settings for
141 the output channel which are to be active during the
142 transfer, and only then. I.e. the settings of the output
143 channel before the transfer are saved, and restored at
144 the end of a transfer, regardless of its success or fail‐
145 ure. None of these options are required, and they default
146 to the settings of the output channel if not specified.
147
149 This document, and the package it describes, will undoubtedly contain
150 bugs and other problems. Please report such in the category transfer
151 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
152 also report any ideas for enhancements you may have for either package
153 and/or documentation.
154 When proposing code changes, please provide unified diffs, i.e the out‐
156 put of diff -u.
157 Note further that attachments are strongly preferred over inlined
159 patches. Attachments can be made by going to the Edit form of the
160 ticket immediately after its creation, and then using the left-most
161 button in the secondary navigation bar.
162
164 channel, copy, transfer
165
167 Transfer module
168
170 Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
171tcllib 0.2 transfer::copy(n)