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

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

KEYWORDS

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