NAME¶
fileutil_traverse - Iterative directory traversal
SYNOPSIS¶
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
DESCRIPTION¶
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.
OPTIONS¶
- -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.
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¶
directory traversal, traversal
CATEGORY¶
Programming tools