fileutil_traverse -
Iterative directory traversal
package require Tcl 8.3
package require fileutil::traverse ? 0.4.2 ?
package require fileutil
package require control
::fileutil::traverse ? objectName ? path ? option value... ?
$traverser command ? arg arg ... ?
$traverser files
$traverser foreach filevar script
$traverser next filevar
This package provides objects for the programmable traversal of
directory hierarchies.
The main command exported by the package is:
-
::fileutil::traverse ? objectName ? path ? option value... ?
-
The command creates a new traversal object with an associated global
Tcl command whose name is objectName. This command may be used
to invoke various operations on the traverser.
If the string %AUTO% is used as the objectName then a
unique name will be generated by the package itself.
Regarding the recognized options see section OPTIONS. Note
that all these options can be set only during the creation of the
traversal object. Changing them later is not possible and causes
errors to be thrown if attempted.
The object command has the following general form:
-
$traverser command ? arg arg ... ?
-
Command and its arguments determine the exact behavior of
the object.
The following commands are possible for traversal objects:
-
$traverser files
-
This method is the most highlevel one provided by traversal
objects. When invoked it returns a list containing the names of all
files and directories matching the current configuration of the
traverser.
-
$traverser foreach filevar script
-
The highlevel files method (see above) is based on this
mid-level method. When invoked it finds all files and directories
matching per the current configuration and executes the script
for each path. The current path under consideration is stored in the
variable named by filevar. Both variable and script live / are
executed in the context of the caller of the method. In the method
files the script simply saves the found paths into the list
to return.
-
$traverser next filevar
-
This is the lowest possible interface to the traverser, the core all
higher methods are built on. When invoked it returns a boolean value
indicating whether it found a path matching the current configuration
(True), or not (False). If a path was found it is
stored into the variable named by filevar, in the context of the
caller.
The foreach method simply calls this method in a loop until
it returned False. This method is exposed so that we are also
able to incrementally traverse a directory hierarchy in an event-based
manner.
-
-prefilter command_prefix
-
This callback is executed for directories. Its result determines if
the traverser recurses into the directory or not. The default is to
always recurse into all directories. The callback is invoked with a
single argument, the absolute path of the directory, and has to
return a boolean value, True when the directory passes the
filter, and False if not.
-
-filter command_prefix
-
This callback is executed for all paths. Its result determines if the
current path is a valid result, and returned by next. The
default is to accept all paths as valid. The callback is invoked with
a single argument, the absolute path to check, and has to
return a boolean value, True when the path passes the filter,
and False if not.
-
-errorcmd command_prefix
-
This callback is executed for all paths the traverser has trouble
with. Like being unable to change into them, get their status,
etc. The default is to ignore any such problems. The callback is
invoked with a two arguments, the absolute path for which the
error occured, and the error message. Errors thrown by the filter
callbacks are handled through this callback too. Errors thrown by the
error callback itself are not caught and ignored, but allowed to pass
to the caller, i.e. however invoked the next. Any other
results from the callback are ignored.
This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category
fileutil of the
http://sourceforge.net/tracker/?group_id=12883.
Please also report any ideas for enhancements you may have for either
package and/or documentation.
directory traversal, traversal