transfer::copy(n)

✨ transfer::copy — Data transfer foundation ✨

okay bestie, so this is transfer::copy, and it's a Tcl manpage from tcllib 💖 it's literally the whole data-transfer foundation, no cap.

---

🌸 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 gives you a whole lil squad of commands for doing asynchronous transfer of info — and that info can live in either a string or a channel, your choice, main character energy 💅

The whole point of this package (the way that it ate, honestly) is that these commands give you a nicer callback API than the builtin command fcopy. Which means using these facilities is lowkey simpler than using the builtin. periodt 🫶

---

👑 API 👑

• transfer::copy::do chan|string data outchannel ?options...? — this command transfers the information in data to the outchannel, following whatever the options say. The type of the information sitting in data gets figured out from that first argument, iykyk.

The options this command accepts are literally the same ones that transfer::copy::options accepts, and they're explained over there.

• chan — the argument data holds the handle of a channel, and the actual information to transfer gets read out of that channel.
• string — the argument data holds a string, and that string is the information to be transfered.

• transfer::copy::chan channel outchannel ?options...? — this one is just a shorter, more direct form of the command transfer::copy::do chan. same vibes, less typing 🧚
• transfer::copy::string string outchannel ?options...? — and this is the shorter, more direct form of transfer::copy::do string. slay.
• transfer::copy::doChan channel outchannel optvar — alternate form of transfer::copy::chan, except it reads its options out of the array variable named by optvar instead of from a variable-length argument list. cute, organized, obsessed.
• transfer::copy::doString string outchannel optvar — alternate form of transfer::copy::string, again reading its options out of the array variable named by optvar rather than a variable-length argument list.
• transfer::copy::options outchannel optionlist optvar — this is the option processor that all the commands above use when they read their options from a variable-length argument list. Here's its whole routine:
  1. it first reads default settings from the channel handle outchannel
  2. then it processes the list of options in optionlist
  3. and at last it stores the results in the array variable named by optvar

The contents of that variable are in a format that's directly understood by every command above that reads its options out of an array variable. no conversion needed, it just gets it 💜

The recognized options are:

• -blocksize int — this specifies the size of the chunks to transfer in one operation. It's optional and defaults to the value of -buffersize as configured for the output channel. If you do specify it, its value has to be an integer number greater than zero. ⭐
• -command commandprefix — this specifies the completion callback of the operation. This option has to be specified. An error will be thrown if it isn't, or if the empty list was specified as its argument. 😭

Its value has to be a command prefix — i.e. a list whose first word is the command to execute, followed by words containing fixed arguments. When the callback gets invoked, one or two additional arguments are appended to the prefix. The first argument is the number of bytes which were transfered. The optional second argument is an error message, and it's added if and only if an error occured during the the transfer.

• -progress commandprefix — this specifies the progress callback of the operation. It's optional and defaults to the empty list. That empty-list possibility signals that no feedback was asked for, and it disables it.

Its value has to be a command prefix, see above — -command has a more detailed explanation. When the callback is invoked, a single additional argument is appended to the prefix. That argument is the number of bytes which were transfered so far. 📈

• -size int — this specifies the number of bytes to read from the input data and transfer. It's optional and defaults to "Transfer everything". Its value has to be an integer number, and any value less than zero has the same meaning, i.e. to transfer all available data. Any other value is the amount of bytes to transfer.

⚠️ heads up bestie: all transfer commands will throw error when their user tries to transfer more data than is available in the input. This happens immediately, before the transfer is actually started, should the input be a string. Otherwise — that is, for a channel as input — the error is thrown the moment the underflow condition is actually detected.

• -encoding encodingname — 💀
• -eofchar eofspec — 💀
• -translation transspec — these three options are the same as are recognized by the builtin command fconfigure, and they provide the settings for the output channel which are to be active during the transfer, and only then. I.e. the settings of the output channel before the transfer are saved, and restored at the end of a transfer, regardless of its success or failure. None of these options are required, and they default to the settings of the output channel if not specified. 🌈

---

🦋 BUGS, IDEAS, FEEDBACK 🦋

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. 🙈 Please report such in the category transfer of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. Please also report any ideas for enhancements you may have for either the package and/or the documentation — we want all of it, fr fr.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, 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>

---

and that's the whole thing, bestie 🫶 this gorgeous lil page came to you courtesy of tcllib, version 0.3, and it's the transfer::copy(n) page. go forth and transfer, you absolute icon 👑💅