ddest(3)



transfer::data::destinationDataltransfer facitransfer::data::destination(3tcl)

______________________________________________________________________________

NAME
       transfer::data::destination - Data destination

SYNOPSIS
       package require Tcl  8.4

       package require snit  ?1.0?

       package require transfer::data::destination  ?0.2?

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

       objectName method ?arg arg ...?

       objectName destroy

       objectName put chunk

       objectName done

       objectName valid msgvar

       objectName receive channel done

______________________________________________________________________________

DESCRIPTION
       This  package  provides  objects mainly describing the destination of a
       data transfer. They are also able to initiate the reception of informa-
       tion from a channel into the described destination.

API
       transfer::data::destination objectName ?options...?
              This command creates a new data destination object with an asso-
              ciated Tcl command whose name is objectName.  This  object  com-
              mand  is explained in full detail in the sections Object command
              and Object methods. The set of supported options is explained in
              section Options.

              The  object  command will be created under the current namespace
              if the objectName is not fully qualified, and in  the  specified
              namespace  otherwise.   The  fully  qualified name of the object
              command is returned as the result of the command.

   OBJECT COMMAND
       All objects created by the ::transfer::data::destination  command  have
       the following general form:

       objectName method ?arg arg ...?
              The  method method and its arg'uments determine the exact behav-
              ior of the command.  See section Object methods for the detailed
              specifications.

   OBJECT METHODS
       objectName destroy
              This  method  destroys  the object. Doing so while the object is
              busy with the reception of information from a channel will cause
              errors  later  on, when the reception completes and tries to ac-
              cess the now missing data structures of the destroyed object.

       objectName put chunk
              The main receptor method. Saves the received chunk of data  into
              the  configured  destination. It has to be called for each piece
              of data received.

       objectName done
              The secondary receptor method. Finalizes the receiver. It has to
              be called when the receiving channel signals EOF. Afterward nei-
              ther itself nor method put can be called anymore.

       objectName valid msgvar
              This method checks the configuration of the object for validity.
              It  returns a boolean flag as result, whose value is True if the
              object is valid, and False otherwise. In  the  latter  case  the
              variable  whose name is stored in msgvar is set to an error mes-
              sage describing the problem found with the configuration. Other-
              wise this variable is not touched.

       objectName receive channel done
              This  method  initiates the reception of data from the specified
              channel. The received data will be 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 addi-
              tional argument.

   OPTIONS
       All data destinations support the options listed below.  It  should  be
       noted  that all are semi-exclusive, each specifying a different type of
       destination and associated information. If these options are  specified
       more  than once then the last option specified is used to actually con-
       figure the object.

       -channel handle
              This option specifies that the destination  of  the  data  is  a
              channel,  and its associated argument is the handle of the chan-
              nel to write the received data to.

       -file path
              This option specifies that 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 specifies that 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, allowing the user to  monitor  the
              progress  of  the  reception of the data. The callback is always
              invoked with one additional argument, the number  of  bytes  re-
              ceived so far.

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 [http://core.tcl.tk/tcllib/reportlist].  Please
       also report any ideas for enhancements you may have for either  package
       and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the out-
       put 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, data destination, transfer

CATEGORY
       Transfer module

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

tcllib                                0.2    transfer::data::destination(3tcl)

Man(1) output converted with man2html
list of all man pages