1[comment {-*- text -*- doctools manpage}] 2[manpage_begin fileutil_traverse n 0.4.1] 3[moddesc {file utilities}] 4[titledesc {Iterative directory traversal}] 5[category {Programming tools}] 6[require Tcl 8.3] 7[require fileutil::traverse [opt 0.4.1]] 8[require fileutil] 9[require control] 10[description] 11[keywords {directory traversal} traversal] 12[para] 13 14This package provides objects for the programmable traversal of 15directory hierarchies. 16 17The main command exported by the package is: 18 19[list_begin definitions] 20 21[call [cmd ::fileutil::traverse] [opt [arg objectName]] \ 22 [arg path] [opt "[arg option] [arg value]..."]] 23 24The command creates a new traversal object with an associated global 25Tcl command whose name is [arg objectName]. This command may be used 26to invoke various operations on the traverser. 27 28If the string [const %AUTO%] is used as the [arg objectName] then a 29unique name will be generated by the package itself. 30 31[para] 32 33Regarding the recognized options see section [sectref OPTIONS]. Note 34that all these options can be set only during the creation of the 35traversal object. Changing them later is not possible and causes 36errors to be thrown if attempted. 37 38[para] 39 40The object command has the following general form: 41 42[list_begin definitions] 43[call [cmd \$traverser] [method command] [opt [arg "arg arg ..."]]] 44 45[arg Command] and its [arg arg]uments determine the exact behavior of 46the object. 47 48[list_end] 49[list_end] 50 51The following commands are possible for traversal objects: 52 53[list_begin definitions] 54 55[call [cmd \$traverser] [method files]] 56 57This method is the most highlevel one provided by traversal 58objects. When invoked it returns a list containing the names of all 59files and directories matching the current configuration of the 60traverser. 61 62 63[call [cmd \$traverser] [method foreach] [arg filevar] [arg script]] 64 65The highlevel [method files] method (see above) is based on this 66mid-level method. When invoked it finds all files and directories 67matching per the current configuration and executes the [arg script] 68for each path. The current path under consideration is stored in the 69variable named by [arg filevar]. Both variable and script live / are 70executed in the context of the caller of the method. In the method 71[method files] the script simply saves the found paths into the list 72to return. 73 74 75[call [cmd \$traverser] [method next] [arg filevar]] 76 77This is the lowest possible interface to the traverser, the core all 78higher methods are built on. When invoked it returns a boolean value 79indicating whether it found a path matching the current configuration 80([const True]), or not ([const False]). If a path was found it is 81stored into the variable named by [arg filevar], in the context of the 82caller. 83 84The [method foreach] method simply calls this method in a loop until 85it returned [const False]. This method is exposed so that we are also 86able to incrementally traverse a directory hierarchy in an event-based 87manner. 88 89[list_end] 90 91 92[section OPTIONS] 93 94[list_begin options] 95[opt_def -prefilter command_prefix] 96 97This callback is executed for directories. Its result determines if 98the traverser recurses into the directory or not. The default is to 99always recurse into all directories. The callback is invoked with a 100single argument, the [emph absolute] path of the directory, and has to 101return a boolean value, [const True] when the directory passes the 102filter, and [const False] if not. 103 104[opt_def -filter command_prefix] 105 106This callback is executed for all paths. Its result determines if the 107current path is a valid result, and returned by [method next]. The 108default is to accept all paths as valid. The callback is invoked with 109a single argument, the [emph absolute] path to check, and has to 110return a boolean value, [const True] when the path passes the filter, 111and [const False] if not. 112 113[opt_def -errorcmd command_prefix] 114 115This callback is executed for all paths the traverser has trouble 116with. Like being unable to change into them, get their status, 117etc. The default is to ignore any such problems. The callback is 118invoked with a two arguments, the [emph absolute] path for which the 119error occured, and the error message. Errors thrown by the filter 120callbacks are handled through this callback too. Errors thrown by the 121error callback itself are not caught and ignored, but allowed to pass 122to the caller, i.e. however invoked the [method next]. Any other 123results from the callback are ignored. 124 125[list_end] 126 127 128[section {BUGS, IDEAS, FEEDBACK}] 129 130This document, and the package it describes, will undoubtedly contain 131bugs and other problems. 132 133Please report such in the category [emph fileutil] of the 134[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 135 136Please also report any ideas for enhancements you may have for either 137package and/or documentation. 138 139 140[manpage_end] 141