NAME

       fileutil_traverse - Iterative directory traversal

SYNOPSIS

       package require Tcl  8.3

       package require fileutil::traverse  ?0.5?

       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.

              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.

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  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

KEYWORDS

       directory traversal, traversal

CATEGORY

       Programming tools