fileutil_traverse(n)            file utilities            fileutil_traverse(n)



______________________________________________________________________________

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



fileutil                             0.4.2                fileutil_traverse(n)
