transfer::copy(3tcl)

💖 transfer::copy — the Data transfer foundation 💖

okay bestie, settle in, because this is transfer::copy from the transfer manual in section 3tcl, and it is literally the whole data transfer foundation. ✨

---

🌸 NAME 🌸

transfer::copy — Data transfer foundation. that's it, that's the vibe. 🎀

---

🦋 SYNOPSIS 🦋

package require Tcl 8.5 9

package require transfer::copy ?0.3?

transfer::copy::do chan|string data outchannel ?options...?

transfer::copy::chan channel outchannel ?options...?

transfer::copy::string string outchannel ?options...?

transfer::copy::doChan channel outchannel optvar

transfer::copy::doString string outchannel optvar

transfer::copy::options outchannel optionlist optvar

---

✨ DESCRIPTION ✨

so this package hands you a whole little squad of commands for doing the asynchronous transfer of info that lives in either a string or a channel. 💅

and here's the point, the main character energy of it all: these commands give you a nicer callback API than the builtin fcopy, which makes using all of this way simpler than the builtin. no cap. 🔥

---

👑 API 👑

• transfer::copy::do chan|string data outchannel ?options...? — this one transfers whatever is in data into outchannel, following the options. which flavor of data you're dealing with? that's decided by the first argument, bestie. 🫶

the options this command takes are exactly the same as the ones transfer::copy::options takes, and they're all explained right there. go look, i'll wait. 💖

• chan — data holds the handle of a channel, and the actual information to transfer gets read from that channel. 📖
• string — data holds a string, and that string is the information being transferred. 🎀

• transfer::copy::chan channel outchannel ?options...? — a shorter, more direct form of transfer::copy::do chan. same energy, less typing. ⭐
• transfer::copy::string string outchannel ?options...? — a shorter, more direct form of transfer::copy::do string. 🦋
• transfer::copy::doChan channel outchannel optvar — an alternate form of transfer::copy::chan that reads its options out of the array variable named by optvar, instead of from a variable-length argument list. 🍓
• transfer::copy::doString string outchannel optvar — an alternate form of transfer::copy::string that reads its options out of the array variable named by optvar, instead of from a variable-length argument list. 🌸
• transfer::copy::options outchannel optionlist optvar — this is the option processor every command above uses when it's reading options from a variable-length argument list. it goes: first it reads the default settings off the channel handle outchannel, then it processes the list of options in optionlist, and finally it stashes the results in the array variable named by optvar. and the contents of that variable? they're in a format that every command above that reads options out of an array variable understands directly. iconic. 👑

---

💜 the recognized options 💜

• -blocksize int — how big the chunks are that get transferred in one operation. optional, and it defaults to whatever -buffersize is configured as for the output channel. if you do specify it, the value has to be an integer number greater than zero. 🧚
• -command commandprefix — the completion callback for the operation. this one has to be specified. an error gets thrown if it isn't, or if the empty list was given as its argument. its value has to be a command prefix, aka a list whose first word is the command to execute, followed by words holding fixed arguments. when the callback fires, one or two extra arguments get appended to the prefix: the first is the number of bytes transferred, and the optional second one is an error message — added if and only if an error occurred during the transfer. 😭
• -progress commandprefix — the progress callback for the operation. optional, defaults to the empty list, and that empty-list possibility is the signal that no feedback was asked for — it disables it. its value has to be a command prefix (see above, or -command for the full breakdown). when this callback fires, a single extra argument gets appended to the prefix: the number of bytes transferred so far. 💫
• -size int — how many bytes to read from the input data and transfer. optional, defaults to "Transfer everything". its value has to be an integer, and any value less than zero means the same thing — transfer all available data. any other value is the amount of bytes to transfer. 🌈

heads up bestie: all the transfer commands throw an error when you try to transfer more data than is actually available in the input. if the input is a string, that happens immediately, before the transfer has even started. otherwise — meaning when the input is a channel — the error gets thrown the moment the underflow condition is actually detected. 💀

• -encoding encodingname
• -eofchar eofspec
• -translation transspec

these three are the same ones the builtin fconfigure recognizes. they set the settings for the output channel that should be active during the transfer, and only then. so like: the output channel's settings from before the transfer are saved, and they get restored at the end of the transfer, regardless of whether it succeeded or failed. none of these are required, and if you don't specify them they default to the output channel's own settings. 🎀

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. please report those in the category transfer of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. also please report any ideas for enhancements you may have for either the package and/or the documentation. we want them. 🫶

when you're proposing code changes, please provide unified diffs, i.e. the output of diff -u.

also note: attachments are strongly preferred over inlined patches. you can attach stuff by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. 💅

---

🌟 KEYWORDS 🌟

channel, copy, transfer

---

🎀 CATEGORY 🎀

Transfer module

---

💖 COPYRIGHT 💖

Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

okay that's the whole page, bestie, you're officially fluent 💅✨

and for the cute sign-off: this little masterpiece comes from tcllib, version 0.3 — go forth and transfer responsibly, mwah 💖🦋🌸