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