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.

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.

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.

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 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 Tcllib Trackers. Please
also report any ideas for enhancements you may have for either
package and/or documentation.