transfer::copy - Data transfer foundation

transfer::copy::dochan|stringdataoutchannel ?options...?
              This  command  transfers  the information in data to the outchannel, according to the options. The
              type of the information in data is determined by the first argument.

              The  options  available  to  this  command  are  the  same  as  are  available  to   the   command
              transfer::copy::options, and explained there.

              chan   The  argument  data contains the handle of a channel and the actual infomration to transfer
                     is read from that channel.

              string The argument data contains a string and this is the information to be transfered.

       transfer::copy::chanchanneloutchannel ?options...?
              This command is a shorter and more direct form for the command transfer::copy::dochan.

       transfer::copy::stringstringoutchannel ?options...?
              This command is a shorter and more direct form for the command transfer::copy::dostring.

       transfer::copy::doChanchanneloutchanneloptvar
              This command is an alternate form of transfer::copy::chan which reads its options out of the array
              variable named by optvar instead of from a variable length argument list.

       transfer::copy::doStringstringoutchanneloptvar
              This command is an alternate form of transfer::copy::string which reads its  options  out  of  the
              array variable named by optvar instead of from a variable length argument list.

       transfer::copy::optionsoutchanneloptionlistoptvar
              This  command is the option processor used by all the commands above which read their options from
              a variable length argument  list.  It  first  reads  default  settings  from  the  channel  handle
              outchannel,  then  processes  the list of options in optionlist, at last stores the results in the
              array variable named by optvar. The contents of that variable are in a format  which  is  directly
              understood by all the commands above which read their options out of an array variable.

              The recognized options are:

              -blocksizeint
                     This  option  specifies the size of the chunks to transfer in one operation. It is optional
                     and defaults to the value of -buffersize as configured for the output channel.

                     If specified its value has to be an integer number greater than zero.

              -commandcommandprefix
                     This option specifies the completion callback of the  operation.  This  option  has  to  be
                     specified.  An  error  will  be  thrown if it is not, or if the empty list was specified as
                     argument to it.

                     Its value has to be a command prefix, i.e. a list  whose  first  word  is  the  command  to
                     execute,  followed by words containing fixed arguments. When the callback is invoked one or
                     two additional arguments are appended to the prefix. The first argument is  the  number  of
                     bytes  which were transfered. The optional second argument is an error message and added if
                     and only if an error occured during the the transfer.

              -progresscommandprefix
                     This option specifies the progress callback of the operation. It is optional  and  defaults
                     to  the  empty  list.  This  last  possibility  signals  that no feedback was asked for and
                     disabled it.

                     Its value has to be a command prefix, see above, -command for a more detailed  explanation.
                     When  the callback is invoked a single additional arguments is appended to the prefix. This
                     argument is the number of bytes which were transfered so far.

              -sizeint
                     This option specifies the number of bytes to read from the input data and transfer.  It  is
                     optional  and defaults to "Transfer everything".  Its value has to be an integer number and
                     any value less than zero has the same meaning, i.e. to transfer  all  available  data.  Any
                     other value is the amount of bytes to transfer.

                     All  transfer commands will throw error an when their user tries to transfer more data than
                     is available in the input. This  happens  immediately,  before  the  transfer  is  actually
                     started,  should  the  input  be  a string. Otherwise the, i.e. for a channel as input, the
                     error is thrown the moment the underflow condition is actually detected.

              -encodingencodingname-eofchareofspec-translationtransspec
                     These options are the same as are recognized by the builtin command fconfigure and  provide
                     the  settings  for  the output channel which are to be active during the transfer, and only
                     then. I.e. the settings of the output channel before the transfer are saved,  and  restored
                     at  the  end of a transfer, regardless of its success or failure. None of these options are
                     required, and they default to the settings of the output channel if not specified.

       This document, and the package it describes, will undoubtedly contain bugs and  other  problems.   Please
       report  such  in  the  category  transfer  of the TcllibTrackers [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 unifieddiffs, 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.

       Transfer module

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

tcllib                                                 0.3                                  transfer::copy(3tcl)

       This  package  provides  a  number  of commands for the asynchronous of information contained in either a
       string or channel. The main point of this package is that the commands here provide a nicer callback  API
       than the builtin command fcopy, making the use of these facilities simpler than the builtin.

       channel, copy, transfer

       transfer::copy - Data transfer foundation

       package require Tcl8.59

       package require transfer::copy?0.3?transfer::copy::dochan|stringdataoutchannel ?options...?

       transfer::copy::chanchanneloutchannel ?options...?

       transfer::copy::stringstringoutchannel ?options...?

       transfer::copy::doChanchanneloutchanneloptvartransfer::copy::doStringstringoutchanneloptvartransfer::copy::optionsoutchanneloptionlistoptvar

________________________________________________________________________________________________________________