[ Tcllib Table Of Contents | Tcllib Index ]
fileutil_traverse(n) 0.4.5 "file utilities"
fileutil_traverse - Iterative directory traversal
- package require Tcl 8.3
- package require fileutil::traverse ?0.4.3?
- package require fileutil
- package require control
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.
Note that the traverser does follow symbolic links, except when doing so would cause it to enter a link-cycle. In other words, the command takes care to not lose itself in infinite loops upon encountering circular link structures. Note that even links which are not followed will still appear in the result.
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. Please also report any ideas for enhancements you may have for either package and/or documentation.