1fileutil_traverse(n) file utilities fileutil_traverse(n)
2______________________________________________________________________________
6
8 fileutil_traverse - Iterative directory traversal
9
11 package require Tcl 8.3
12 package require fileutil::traverse ?0.4?
14 ::fileutil::traverse ?objectName? path ?option value...?
16 $traverser command ?arg arg ...?
18 $traverser files
20 $traverser foreach filevar script
22 $traverser next filevar
24_________________________________________________________________
26
28 This package provides objects for the programmable traversal of direc‐
29 tory hierarchies. The main command exported by the package is:
30 ::fileutil::traverse ?objectName? path ?option value...?
32 The command creates a new traversal object with an associated
33 global Tcl command whose name is objectName. This command may be
34 used to invoke various operations on the traverser. If the
35 string %AUTO% is used as the objectName then a unique name will
36 be generated by the package itself.
37 Regarding the recognized options see section OPTIONS. Note that
39 all these options can be set only during the creation of the
40 traversal object. Changing them later is not possible and causes
41 errors to be thrown if attempted.
42 The object command has the following general form:
44 $traverser command ?arg arg ...?
46 Command and its arguments determine the exact behavior of
47 the object.
48 The following commands are possible for traversal objects:
50 $traverser files
52 This method is the most highlevel one provided by traversal
53 objects. When invoked it returns a list containing the names of
54 all files and directories matching the current configuration of
55 the traverser.
56 $traverser foreach filevar script
58 The highlevel files method (see above) is based on this mid-
59 level method. When invoked it finds all files and directories
60 matching per the current configuration and executes the script
61 for each path. The current path under consideration is stored in
62 the variable named by filevar. Both variable and script live /
63 are executed in the context of the caller of the method. In the
64 method files the script simply saves the found paths into the
65 list to return.
66 $traverser next filevar
68 This is the lowest possible interface to the traverser, the core
69 all higher methods are built on. When invoked it returns a bool‐
70 ean value indicating whether it found a path matching the cur‐
71 rent configuration (True), or not (False). If a path was found
72 it is stored into the variable named by filevar, in the context
73 of the caller. The foreach method simply calls this method in a
74 loop until it returned False. This method is exposed so that we
75 are also able to incrementally traverse a directory hierarchy in
76 an event-based manner.
77
79 -prefilter command_prefix
80 This callback is executed for directories. Its result determines
81 if the traverser recurses into the directory or not. The default
82 is to always recurse into all directories. The callback is
83 invoked with a single argument, the absolute path of the direc‐
84 tory, and has to return a boolean value, True when the directory
85 passes the filter, and False if not.
86 -filter command_prefix
88 This callback is executed for all paths. Its result determines
89 if the current path is a valid result, and returned by next. The
90 default is to accept all paths as valid. The callback is invoked
91 with a single argument, the absolute path to check, and has to
92 return a boolean value, True when the path passes the filter,
93 and False if not.
94 -errorcmd command_prefix
96 This callback is executed for all paths the traverser has trou‐
97 ble with. Like being unable to change into them, get their sta‐
98 tus, etc. The default is to ignore any such problems. The call‐
99 back is invoked with a two arguments, the absolute path for
100 which the error occured, and the error message. Errors thrown by
101 the filter callbacks are handled through this callback too.
102 Errors thrown by the error callback itself are not caught and
103 ignored, but allowed to pass to the caller, i.e. however invoked
104 the next. Any other results from the callback are ignored.
105
107 This document, and the package it describes, will undoubtedly contain
108 bugs and other problems. Please report such in the category fileutil
109 of the Tcllib SF Trackers [http://source‐
110 forge.net/tracker/?group_id=12883]. Please also report any ideas for
111 enhancements you may have for either package and/or documentation.
112
114 directory traversal, traversal
115fileutil 0.4 fileutil_traverse(n)