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.1?

       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 traver-
	      sal 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.1						      fileutil_traverse(n)