DDEST(n)

💖 transfer::data::destination(n) — the data destination glow-up 💖

okay bestie, listen. this is a Tcl manpage from the tcllib family, and it's all about where the data goes. no cap. it lives in the transfer module and its whole thing is describing a destination for a data transfer — and also being able to kick off receiving info from a channel into that destination. iconic behaviour honestly. 🎀

---

✨ NAME ✨

transfer::data::destination — Data destination 💅

---

✨ 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 ✨

so this package hands you objects whose main character energy is describing the destination of a data transfer. 🦋

and they don't just sit there looking pretty — they can also initiate the reception of information from a channel straight into the destination they're describing. multitasking queen. 👑

---

✨ API ✨

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

this command makes you a brand-new data destination object, and that object comes with its own associated Tcl command whose name is objectName. 💫

that object command gets explained in full detail down in Object command and Object methods (below, bestie, keep scrolling). and the whole set of supported options is explained in Options. 🫶

quick note on naming: the object command gets created under the current namespace if objectName isn't fully qualified — and in the specified namespace otherwise. the fully qualified name of the object command is what you get back as the result of the command. 🎁

---

🎀 OBJECT COMMAND

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

objectName method ?arg arg ...?

the method method plus its arg'uments decide the exact behaviour of the command. for the detailed specs, go read Object methods. it's giving delegation. 💅

---

🎀 OBJECT METHODS

💀 objectName destroy

this method destroys the object. periodt.

⚠️ but be careful bestie: doing this while the object is busy receiving information from a channel will cause errors later on — specifically when the reception completes and tries to access the now-missing data structures of the destroyed object. it's giving haunted. 😭

🍓 objectName put chunk

the main receptor method. it saves the received chunk of data into the configured destination.

you have to call it for each piece of data received. every single one. no skipping. ✨

🌈 objectName done

the secondary receptor method. it finalizes the receiver, and you have to call it when the receiving channel signals EOF.

after that? neither itself nor put can be called anymore. it's over, it's done, no take-backs. 🙈

💜 objectName valid msgvar

this method checks the configuration of the object for validity. 🕵️♀️

it returns a boolean flag as its result:

• True if the object is valid 💚
• False otherwise 💔

in that False case, the variable whose name is stored in msgvar gets set to an error message describing the problem it found with the configuration. otherwise, that variable is not touched — hands off, respectfully. ✋

🦋 objectName receive channel done

this method initiates the reception of data from the specified channel. the received data 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. that's it, that's the whole payload. 👑

---

✨ OPTIONS ✨

all data destinations support the options listed below. 💖

important vibe check: all of these are semi-exclusive — each one specifies a different type of destination plus its associated info. and if you specify these options more than once, then the last option specified is the one used to actually configure the object. last one wins, always. 👑

• -channel handle — this option says the destination of the data is a channel, and its associated argument is the handle of the channel to write the received data to. 🎀
• -file path — this option says the destination of the data is a file, and its associated argument is the path of the file to write the received data to. 🍓
• -variable varname — this option says the destination of the data is a variable, and its associated 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 — this option, if specified, defines a command to be invoked for each chunk of bytes received, letting you monitor the progress of the reception of the data. the callback is always invoked with one additional argument: the number of bytes received so far. progress bar era. 📈

---

✨ BUGS, IDEAS, FEEDBACK ✨

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. 😭 that's just how it is. please report them in the category transfer of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also report any ideas for enhancements you have for either the package and/or the documentation. we love a glow-up suggestion. 💅

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

also 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. iykyk. 🌟

---

✨ KEYWORDS ✨

channel, copy, data destination, transfer 🌈

---

✨ CATEGORY ✨

Transfer module 🎀

---

✨ COPYRIGHT ✨

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

---

and that's the whole page bestie!! 💖 this one's from tcllib, version 0.3, and it's the transfer::...destination(n) page — she's a legend, she's a queen, she's a data destination. mwah, go forth and receive responsibly. 👑✨🦋