transfer::data::source(n)

✨ transfer::data::source(n) ✨

okay so bestie, welcome to transfer::data::source — it lives in the Data transfer facilities corner of the tcllib universe, and today we're gonna make it make sense 💖

---

🌸 NAME 🌸

transfer::data::source — Data source (yes queen, that's literally the whole job description)

---

✨ 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 this package hands you objects that mostly just... describe where some data is coming from before you yeet it somewhere 🦋. They're the origin story of a transfer, fr fr.

And they're not just decorative — they can also initiate the actual transfer of the information they're describing onto a channel, using the foundation package transfer::copy. Slay 💖

---

🎀 API 🎀

👑 PACKAGE COMMANDS 👑

• transfer::data::source objectName ? options... ? — this command creates a brand-new data source object, and that object gets its very own Tcl command, whose name is objectName. That object command is explained in full detail down in the Object command and Object methods sections, and the options it supports are all in the Options section. Also: if objectName isn't fully qualified, the object command gets created under the current namespace; if it is fully qualified, it lands in whatever namespace you specified. Either way, the fully qualified name of the object command is returned as the result. periodt 💅

🦋 OBJECT COMMAND 🦋

Every object made by the ::transfer::data::source command has this same general form:

• objectName method ? arg arg ... ? — the method and its arguments decide exactly what the command does. Full specs live in the Object methods section, bestie 💖

🌈 OBJECT METHODS 🌈

• objectName destroy — this method destroys the object. And ngl, doing that while a transfer started by the object is still active is totally safe ✅ — because all the data the transfer itself needs was already copied, and when the transfer finishes it will not try to touch the initiating object ever again. iykyk: the transfer is completely separate from the source object itself. main character energy 🫶
• objectName type — this method returns a string describing the type of data the object is referring to. The possible values and what they mean:
  • undefined — no data was specified at all, or it was specified incompletely. Basically the object has no idea what type it is 😭
  • string — the data to transfer is contained in a string.
  • channel — the data to transfer is contained in a channel.
• objectName data — this method returns a value depending on the type of data the object refers to, and that's your way in to actually access the data. Heads up though: it throws an error if the type is undefined 💀. For type string the returned result is the data itself; for type channel the returned result is the handle of the channel holding the data.
• objectName size — this method returns a value depending on the type of data the object refers to: the size of the data. It also throws an error if the type is undefined. And ooh, important: returning a negative value signals that the object simply can't figure out an absolute size upfront — like, say, for data sitting in a channel 🙈
• objectName valid msgvar — this method checks whether the object's configuration is valid. It returns a boolean flag: 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. not me being thorough ✨
• objectName transmit channel blocksize done — this method kicks off a transfer of the referenced data to the specified channel 🚀. When the transfer completes, the command prefix done is invoked, following the rules for the option -command of the 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 the command transfer::copy::do in the package transfer::copy. go off 👑

---

⭐ OPTIONS ⭐

All data sources support the options listed below 💖. Now listen closely, because there's a little twist: the first four options are semi-exclusive — each one specifies a different type of data source plus its associated content. And if you specify more than one of them, then the last option specified is the one that actually configures the object. no take-backsies 💅

• -string text — says the source of the data is an immediate string, and its associated argument contains 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 contains the name of the variable in question. That variable is assumed to be global or namespaced, anchored at the global namespace.
• -size int — this one specifies the size of the data transfer. It's optional and defaults to -1. And just so you know: this value, and any other value less than zero, signals to transfer all the data from the source 🦋
• -progress command — if you specify this, it defines a command to be invoked for each chunk of bytes transmitted, letting you monitor how the transmission is going 👀. The callback is always invoked with one additional argument: the number of bytes transmitted so far. obsessed 💖

---

💀 BUGS, IDEAS, FEEDBACK 💀

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 🙏.

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. slay 🎀

---

🔥 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 🫶 it's from tcllib, it's version 0.3, and the page itself is transfer::data::source(n). mwah 💖✨