DSOURCE(3tcl)

transfer::data::source 💖✨

okay bestie, gather round, because this is the Data source page from the tcllib manual (section 3tcl, under the whole Data transfer facilities umbrella) and honestly? it's giving foundational. 🎀

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9
package require snit ?1.0?
package require transfer::copy ?0.3?
package require transfer::data::source ?0.3?

transfer::data::source objectName ?options...?

objectName method ?arg arg ...?
objectName destroy
objectName type
objectName data
objectName size
objectName valid msgvar
objectName transmit channel blocksize done

---

🌸 DESCRIPTION 🌸

So basically 💅 this package hands you objects that mostly just describe where some data is coming from before it gets transferred. That's the vibe. But not just describing — they can also kick off the actual transfer of the info they describe, pushing it to a channel, using the foundation package transfer::copy. 🦋

---

👑 API 👑

PACKAGE COMMANDS

• transfer::data::source objectName ?options...? — this makes a brand new data source object, and the object gets its own little Tcl command named objectName. 🫶 The whole deal with that object command is spelled out in full in the sections Object command and Object methods, and all the options you can pass live in the Options section.

If objectName isn't fully qualified, the object command gets created under the current namespace — otherwise it lands in the namespace you actually specified. The fully qualified name of the object command is what comes back as the result. ⭐

OBJECT COMMAND

Every single object made by ::transfer::data::source follows this general shape:

• objectName method ?arg arg ...? — the method, plus whatever arg'uments you give it, decides exactly what the command does. Detailed specs live in Object methods. 💖

OBJECT METHODS

• objectName destroy — destroys the object. And yes, it's totally safe to do this while a transfer the object started is still running, because all the data the transfer needs was already copied out. The completion of the transfer won't try to touch the initiating object ever again, i.e. the transfer is completely separate from the source object itself. no cap. 🧚
• objectName type — returns a string describing what type of data this object is referring to. The possible values and what they mean:
  • undefined — no data was specified at all, or it was given incompletely. The object genuinely does not know the type. 💀
  • string — the data to transfer is sitting in a string.
  • channel — the data to transfer is sitting in a channel.
• objectName data — returns a value that depends on the type of data the object refers to, and that's your way in to actually access the data. It throws an error if the type is undefined. For type string you get the data itself back; for type channel you get the handle of the channel holding the data. 🌈
• objectName size — returns a value depending on the type, specifically the size of the data. Throws an error if the type is undefined. And heads up: if it returns a negative value, that's the signal that the object can't work out an absolute size upfront — like, say, for data in a channel. 🙈
• objectName valid msgvar — checks whether the object's configuration is valid, returning a boolean. True means valid, False means nope. In the nope case, the variable whose name is stored in msgvar gets set to an error message describing the problem found with the configuration. Otherwise that variable is left completely untouched. 🎀
• objectName transmit channel blocksize done — this one actually initiates a transfer of the referenced data to the specified channel. 🔥 When the transfer completes, the command prefix done gets invoked, following the rules for the option -command of command transfer::copy::do in the package transfer::copy. The blocksize says how big the chunks are that get transferred in one go — see the option -blocksize of command transfer::copy::do in the package transfer::copy.

OPTIONS

All data sources support the options listed below. Important lil note: the first four options are semi-exclusive — each one specifies a different type of data source and its associated content. If you specify more than one of them, then the last option specified is the one that actually configures the object. periodt. 💅

• -string text — says the source of the data is an immediate string, and its associated argument holds the string in question.
• -channel handle — says the source of the data is a channel, and its associated argument is the handle of the channel containing the data.
• -file path — says the source of the data is a file, and its associated argument is the path of the file containing the data.
• -variable varname — says the source of the data is a string stored in a variable, and its associated argument holds the name of the variable in question. The variable is assumed to be global or namespaced, anchored at the global namespace. 🦋
• -size int — specifies the size of the data transfer. It's optional and defaults to -1. This value, and any other value less than zero, signals to transfer all the data from the source.
• -progress command — if you set this, it defines a command to invoke for each chunk of bytes transmitted, so you can monitor how the transmission is going. The callback is always invoked with one additional argument: the number of bytes transmitted so far. ✨

---

😭 BUGS, IDEAS, FEEDBACK 😭

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. Please report them 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 love feedback. 🫶

When 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 right after creating it, and then using the left-most button in the secondary navigation bar. 💖

---

⭐ KEYWORDS ⭐

channel, copy, data source, transfer

---

🎀 CATEGORY 🎀

Transfer module

---

💜 COPYRIGHT 💜

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

---

and that's the whole page bestie!! 🌸 this was tcllib version 0.3, and if you ever need to find it again, it's filed under transfer::...a::source(3tcl). slay, go transfer some data responsibly 💅✨🦋