fileutil::multi::op(n)          file utilities          fileutil::multi::op(n)



______________________________________________________________________________

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



fileutil                             0.5.3              fileutil::multi::op(n)
