multiop(3tcl)
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.
KEYWORDS
copy, file utilities, move, multi-file, remove
CATEGORY
Programming tools
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
