Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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 com-mand command
       mand 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 file-var. filevar.
              var. 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 vari-able variable
              able 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 call-back callback
              back 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://source -
       forge.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)