trusty (3) traverse.3tcl.gz

NAME

       fileutil_traverse - Iterative directory traversal

SYNOPSIS

       package require Tcl  8.3

       package require fileutil::traverse  ?0.4.3?

       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