transfer...stination(3tcl)

💖 NAME 💖

transfer::data::destination — the data destination, bestie 💅

So like, this is transfer::data::destination, a page from the <pink>3tcl</pink> manual, living under the big <purple>Data transfer facilities</purple> umbrella. Let's go ✨

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require snit ?1.0?

package require transfer::data::destination ?0.3?

transfer::data::destination objectName ?options...?

objectName method ?arg arg ...?

objectName destroy

objectName put chunk

objectName done

objectName valid msgvar

objectName receive channel done

---

🦋 DESCRIPTION 🦋

Okay so this package hands you objects that are, like, mainly about describing where data is going — the destination of a data transfer, periodt. 💫

But wait, there's more (there's always more): these objects can also kick off the reception of information coming from a channel, dropping it right into the destination they describe. Slay. 👑

---

⭐ API ⭐

✨ transfer::data::destination objectName ?options...? ✨

This command creates a brand new data destination object, and that object comes with its very own Tcl command whose name is objectName. The whole personality of that object command is explained in full detail in the sections Object command and Object methods — go read those, fr fr. And the set of supported options? That's all in the Options section. 🎀

Where does the object command live? If objectName is not fully qualified, it gets created under the current namespace. If it is fully qualified, it goes in the namespace you specified. Either way, the command hands you back the fully qualified name of the object command as its result. 💖

---

🫶 OBJECT COMMAND 🫶

Every single object created by the ::transfer::data::destination command has this general form:

objectName method ?arg arg ...?

The method method plus its arg'uments decide the exact behaviour of the command. Detailed specs? Section Object methods, obviously. 😌

---

💅 OBJECT METHODS 💅

objectName destroy

This method destroys the object. Now listen — if you do this while the object is busy receiving information from a channel, you're gonna get errors later on, when the reception finishes and tries to reach for the data structures of the object you already yeeted into the void. So like, don't do that. 💀

objectName put chunk

The main receptor method. It saves the received chunk of data into whatever destination you configured. You have to call this for each piece of data received. No skipping. 🙈

objectName done

The secondary receptor method. It finalizes the receiver. You have to call it when the receiving channel signals EOF. After that? Neither this method nor put can be called anymore. Closed for business, bestie. 🚪

objectName valid msgvar

This method checks the configuration of the object for validity. It returns a boolean flag: True if the object is valid, False otherwise. And in that second case, the variable whose name is stored in msgvar gets set to an error message describing the problem it found with the configuration. If everything's fine, that variable doesn't get touched at all. 🤷‍♀️

objectName receive channel done

This method initiates the reception of data from the specified channel. The data it receives gets stored into the configured destination, via calls to the methods put and done. When the reception completes, the command prefix done is invoked, with the number of received characters appended to it as the sole additional argument. 💫

---

🔥 OPTIONS 🔥

Every data destination supports the options below. Real talk though: they're all semi-exclusive — each one specifies a different type of destination plus its associated info. So if you specify these options more than once, it's the last one you specified that actually configures the object. Last one wins, iykyk. 👑

• -channel handle — says the destination of the data is a channel, and its argument is the handle of the channel to write the received data to. 📡
• -file path — says the destination of the data is a file, and its argument is the path of the file to write the received data to. 📁
• -variable varname — says the destination of the data is a variable, and its argument contains the name of the variable to write the received data to. The variable is assumed to be global or namespaced, anchored at the global namespace. 🌍
• -progress command — if you specify this one, it defines a command to be invoked for each chunk of bytes received, letting you monitor the progress of the data reception. The callback is always invoked with one additional argument: the number of bytes received so far. 📊

---

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. I know, I know, tragic. 💔 Please report such in the category transfer of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist](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 love ideas. 🫶

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

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. That's the vibe. ✨

---

🌈 KEYWORDS 🌈

channel, copy, data destination, transfer

---

👑 CATEGORY 👑

Transfer module

---

💜 COPYRIGHT 💜

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

---

okay that's the whole page, you ate it, no crumbs 🍓 This was transfer::data::destination out of the <purple>tcllib</purple> docs, version <hotpink>0.3</hotpink>, sitting pretty in section <cyan>3tcl</cyan> — mwah, bye bestie 💖✨🎀