Provided by: tcllib_1.15-dfsg-2_all bug

NAME

       fileutil::multi::op - Multi-file operation, scatter/gather

SYNOPSIS

       package require Tcl  8.4

       package require fileutil::multi::op  ?0.5.3?

       package require wip  ?1.0?

       ::fileutil::multi::op ?opName? ?word...?

       opName option ?arg arg ...?

       $opName do ?word...?

       into directory

       in directory

       to directory

       from directory

       not pattern

       for pattern

       exclude pattern

       but

       except

       as name

       recursive

       recursively

       copy

       move

       remove

       expand

       invoke cmdprefix

       reset

       (

       )

       cd directory

       up

       for-windows

       for-win

       for-unix

       the pattern

       the-set varname

       -> varname

       strict

       !strict

       files

       links

       directories

       dirs

       all

       state?

       as?

       excluded?

       from?

       into?

       operation?

       recursive?

       strict?

       type?

_________________________________________________________________

DESCRIPTION

       This package provides objects which are able to perform actions on multiple files selected
       by glob patterns.

       At the core is a domain specific language allowing the easy  specification  of  multi-file
       copy  and/or  move  and/or  deletion  operations.  Alternate names would be scatter/gather
       processor, or maybe even assembler.

CLASS API

       The main command of the package is:

       ::fileutil::multi::op ?opName? ?word...?
              The command creates a new multi-file operation object with an associated global Tcl
              command  whose  name  is  opName.   This  command can be used to invoke the various
              possible file operations.  It has the following general form:

              opName option ?arg arg ...?
                     Option and the args determine the exact behavior of the command.

       If the string %AUTO% is used as the opName then the package will generate a unique name on
       its own.

       If one or more words are specified they are interpreted as an initial set of file commands
       to execute. I.e. the method do of the newly constructed object is implicitly invoked using
       the words as its arguments.

OBJECT API

       The following methods are possible for multi-file operation objects:

       $opName do ?word...?
              This  method  interprets  the  specified words as file commands to execute. See the
              section FILE API for the set of acceptable commands, their syntax, and semantics.

              The result of the method is the result  generated  by  the  last  file  command  it
              executed.

FILE API

       Both  object  constructor  and  method  do take a list of words and interpret them as file
       commands to execute. The names were chosen to allow  the  construction  of  operations  as
       sentences  in  near-natural language. Most of the commands influence just the state of the
       object, i.e. are simply providing the configuration used by  the  command  triggering  the
       actual action.

       into directory
              Specifies the destination directory for operations.

       in directory
              Alias for into.

       to directory
              Alias for into.

       from directory
              Specifies the source directory for operations.

       not pattern
              Specifies a glob pattern for paths to be excluded from the operation.

       for pattern
              Alias for not.

       exclude pattern
              Alias for not.

       but    Has  no arguments of its own, but looks ahead in the list of words and executes all
              not commands immediately following it. This allows the construction  of  "but  not"
              and  "but  exclude"  clauses  for a more natural sounding specification of excluded
              paths.

       except A semi-alias for but. Has no arguments of its own, but looks ahead in the  list  of
              words  and  executes  all  for  commands  immediately following it. This allows the
              construction of "except for" clauses for a more natural sounding  specification  of
              excluded paths.

       as name
              Specifies  a new name for the first file handled by the current operation. I.e. for
              the renaming of a single file during the operation.

       recursive
              Signals that file expansion should happen in the whole directory hierarchy and  not
              just the directory itself.

       recursively
              An alias for recursive.

       copy   Signals  that  the  operation  is  the  copying of files from source to destination
              directory per the specified inclusion and exclusion patterns.

       move   Signals that the operation is the  moving  of  files  from  source  to  destination
              directory per the specified inclusion and exclusion patterns.

       remove Signals that the operation is the removal of files in the destination directory per
              the specified inclusion and exclusion patterns.

       expand Signals that there is no operation but the calculation of the set of files from the
              include and exclude patterns. This operation is not available if the-set is used.

       invoke cmdprefix
              Signals  that  the  user-specified  command  prefix  cmdprefix  is the operation to
              perform. The command prefix is executed at the global level and  given  the  source
              directory,  destination  directory,  and  set  of files (as dictionary mapping from
              source to destination files), in this order.

       reset  Forces the object into the ground state where all parts of the  configuration  have
              default values.

       (      Saves a copy of the current object state on a stack.

       )      Takes  the  state  at the top of the state stack and restores it, i.e. makes it the
              new current object state.

       cd directory
              Changes the destination directory to the sub-directory  directory  of  the  current
              destination.

       up     Changes   the  destination  directory  to  the  parent  directory  of  the  current
              destination.

       for-windows
              Checks that Windows is the current platform. Aborts processing if not.

       for-win
              An alias for for-windows.

       for-unix
              Checks that Unix is the current platform. Aborts processing if not.

       the pattern
              This command specifies the files to operate on per a glob pattern, and is also  the
              active  element,  i.e. the command which actually performs the specified operation.
              All the other commands only modified the object state to set the operation up,  but
              di nothing else.

              To  allow  for  a more natural sounding syntax this command also looks ahead in the
              list of words looks and executes several commands immediately following  it  before
              performing its own actions.  These commands are as, but, exclude, except, from, and
              into (and aliases). That way these commands act like  qualifiers,  and  still  take
              effect as if they had been written before this command.

              After  the  operation  has been performed the object state the exclude patterns and
              the alias name, if specified, are reset to their default values (i.e.  empty),  but
              nothing else.

       the-set varname
              Like  the,  however  the set of files to use is not specified implicitly per a glob
              pattern, but contained and loaded from the specified variable. The operation expand
              is not available if this command is used.

       -> varname
              Saves the set of files from the last expansion into the specified variable.

       strict Make  file  expansion  and  definition  of  destination  directory (in and aliases)
              strict, i.e. report errors for missing directories, and empty expansion.

       !strict
              Complement of strict. A missing destination directory or empty  expansion  are  not
              reported as errors.

       files  Limit the search to files. Default is to accept every type of path.

       links  Limit the search to symbolic links. Default is to accept every type of path.

       directories
              Limit the search to directories. Default is to accept every type of path.

       dirs   An alias for directories.

       all    Accept all types of paths (default).

       state? Returns  the  current  state  of  the object as dictionary. The dictionary keys and
              their meanings are:

              as     Last setting made by as.

              excluded
                     List of currently known exclusion patterns.

              from   Current source directory, set by from.

              into   Current destination directory, set by into (and aliases).

              operation
                     Current operation to perform, set by copy, move, remove, expand, or invoke.

              recursive
                     Current recursion status. Set/unset by recursive and !recursive.

              strict Current strictness. Set/unset by strict and !strict.

              type   Current path type limiter. Set by either files, directories, links, or all.

       as?    Returns the current alias name.

       excluded?
              Returns the current set of exclusion patterns.

       from?  Returns the current source directory.

       into?  Returns the current destination directory.

       operation?
              Returns the current operation to perform.

       recursive?
              Returns the current recursion status.

       strict?
              Returns the current strictness.

       type?  Returns the current path type limiter.

EXAMPLES

       The following examples assume that the variable F contains a  reference  to  a  multi-file
       operation object.
              $F do copy                       \\
              the  *.dll                    \\
              from c:/TDK/PrivateOpenSSL/bin \\
              to   [installdir_of tls]
              $F do move      \\
              the  *       \\
              from /sources \\
              into /scratch  \\
              but not *.html
              # Alternatively use 'except for *.html'.
              $F do           \\
              move         \\
              the  index    \\
              from /sources  \\
              into /scratch   \\
              as   pkgIndex.tcl
              $F do         \\
              remove     \\
              the *.txt  \\
              in /scratch
       Note  that  the fact that most commands just modify the object state allows us to use more
       off forms as specifications  instead  of  just  nearly-natural  language  sentences.   For
       example the second example in this section can re-arranged into:
              $F do            \\
              from /sources \\
              into /scratch  \\
              but not *.html \\
              move           \\
              the  *
       and  the  result  is  not  only  still  a  valid  specification, but even stays relatively
       readable.

       Further note that the information collected  by  the  commands  but,  except,  and  as  is
       automatically reset after the associated the was executed. However no other state is reset
       in that manner, allowing the user to avoid  repetitions  of  unchanging  information.  For
       example the second and third examples of this section can be merged and rewritten into the
       equivalent:
              $F do                   \\
              move                 \\
              the  *                \\
              from /sources          \\
              into /scratch           \\
              but not *.html not index \\
              the  index               \\
              as   pkgIndex.tcl

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.   Please  report  such  in  the  category  fileutil  of  the  Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].   Please  also  report  any  ideas   for
       enhancements you may have for either package and/or documentation.

KEYWORDS

       copy, file utilities, move, multi-file, remove

CATEGORY

       Programming tools