1fileutil::multi::op(n) file utilities fileutil::multi::op(n)
2______________________________________________________________________________
6
8 fileutil::multi::op - Multi-file operation, scatter/gather
9
11 package require Tcl 8.4
12 package require fileutil::multi::op ?0.5.3?
14 package require wip ?1.0?
16 ::fileutil::multi::op ?opName? ?word...?
18 opName option ?arg arg ...?
20 $opName do ?word...?
22 into directory
24 in directory
26 to directory
28 from directory
30 not pattern
32 for pattern
34 exclude pattern
36 but
38 except
40 as name
42 recursive
44 recursively
46 copy
48 move
50 remove
52 expand
54 invoke cmdprefix
56 reset
58 (
60 )
62 cd directory
64 up
66 for-windows
68 for-win
70 for-unix
72 the pattern
74 the-set varname
76 -> varname
78 strict
80 !strict
82 files
84 links
86 directories
88 dirs
90 all
92 state?
94 as?
96 excluded?
98 from?
100 into?
102 operation?
104 recursive?
106 strict?
108 type?
110______________________________________________________________________________
112
114 This package provides objects which are able to perform actions on mul‐
115 tiple files selected by glob patterns.
116 At the core is a domain specific language allowing the easy specifica‐
118 tion of multi-file copy and/or move and/or deletion operations. Alter‐
119 nate names would be scatter/gather processor, or maybe even assembler.
120
122 The main command of the package is:
123 ::fileutil::multi::op ?opName? ?word...?
125 The command creates a new multi-file operation object with an
126 associated global Tcl command whose name is opName. This com‐
127 mand can be used to invoke the various possible file operations.
128 It has the following general form:
129 opName option ?arg arg ...?
131 Option and the args determine the exact behavior of the
132 command.
133 If the string %AUTO% is used as the opName then the package will gener‐
135 ate a unique name on its own.
136 If one or more words are specified they are interpreted as an initial
138 set of file commands to execute. I.e. the method do of the newly con‐
139 structed object is implicitly invoked using the words as its arguments.
140
142 The following methods are possible for multi-file operation objects:
143 $opName do ?word...?
145 This method interprets the specified words as file commands to
146 execute. See the section FILE API for the set of acceptable com‐
147 mands, their syntax, and semantics.
148 The result of the method is the result generated by the last
150 file command it executed.
151
153 Both object constructor and method do take a list of words and inter‐
154 pret them as file commands to execute. The names were chosen to allow
155 the construction of operations as sentences in near-natural language.
156 Most of the commands influence just the state of the object, i.e. are
157 simply providing the configuration used by the command triggering the
158 actual action.
159 into directory
161 Specifies the destination directory for operations.
162 in directory
164 Alias for into.
165 to directory
167 Alias for into.
168 from directory
170 Specifies the source directory for operations.
171 not pattern
173 Specifies a glob pattern for paths to be excluded from the oper‐
174 ation.
175 for pattern
177 Alias for not.
178 exclude pattern
180 Alias for not.
181 but Has no arguments of its own, but looks ahead in the list of
183 words and executes all not commands immediately following it.
184 This allows the construction of "but not" and "but exclude"
185 clauses for a more natural sounding specification of excluded
186 paths.
187 except A semi-alias for but. Has no arguments of its own, but looks
189 ahead in the list of words and executes all for commands immedi‐
190 ately following it. This allows the construction of "except for"
191 clauses for a more natural sounding specification of excluded
192 paths.
193 as name
195 Specifies a new name for the first file handled by the current
196 operation. I.e. for the renaming of a single file during the op‐
197 eration.
198 recursive
200 Signals that file expansion should happen in the whole directory
201 hierarchy and not just the directory itself.
202 recursively
204 An alias for recursive.
205 copy Signals that the operation is the copying of files from source
207 to destination directory per the specified inclusion and exclu‐
208 sion patterns.
209 move Signals that the operation is the moving of files from source to
211 destination directory per the specified inclusion and exclusion
212 patterns.
213 remove Signals that the operation is the removal of files in the desti‐
215 nation directory per the specified inclusion and exclusion pat‐
216 terns.
217 expand Signals that there is no operation but the calculation of the
219 set of files from the include and exclude patterns. This opera‐
220 tion is not available if the-set is used.
221 invoke cmdprefix
223 Signals that the user-specified command prefix cmdprefix is the
224 operation to perform. The command prefix is executed at the
225 global level and given the source directory, destination direc‐
226 tory, and set of files (as dictionary mapping from source to
227 destination files), in this order.
228 reset Forces the object into the ground state where all parts of the
230 configuration have default values.
231 ( Saves a copy of the current object state on a stack.
233 ) Takes the state at the top of the state stack and restores it,
235 i.e. makes it the new current object state.
236 cd directory
238 Changes the destination directory to the sub-directory directory
239 of the current destination.
240 up Changes the destination directory to the parent directory of the
242 current destination.
243 for-windows
245 Checks that Windows is the current platform. Aborts processing
246 if not.
247 for-win
249 An alias for for-windows.
250 for-unix
252 Checks that Unix is the current platform. Aborts processing if
253 not.
254 the pattern
256 This command specifies the files to operate on per a glob pat‐
257 tern, and is also the active element, i.e. the command which ac‐
258 tually performs the specified operation. All the other commands
259 only modified the object state to set the operation up, but di
260 nothing else.
261 To allow for a more natural sounding syntax this command also
263 looks ahead in the list of words looks and executes several com‐
264 mands immediately following it before performing its own ac‐
265 tions. These commands are as, but, exclude, except, from, and
266 into (and aliases). That way these commands act like qualifiers,
267 and still take effect as if they had been written before this
268 command.
269 After the operation has been performed the object state the ex‐
271 clude patterns and the alias name, if specified, are reset to
272 their default values (i.e. empty), but nothing else.
273 the-set varname
275 Like the, however the set of files to use is not specified im‐
276 plicitly per a glob pattern, but contained and loaded from the
277 specified variable. The operation expand is not available if
278 this command is used.
279 -> varname
281 Saves the set of files from the last expansion into the speci‐
282 fied variable.
283 strict Make file expansion and definition of destination directory (in
285 and aliases) strict, i.e. report errors for missing directories,
286 and empty expansion.
287 !strict
289 Complement of strict. A missing destination directory or empty
290 expansion are not reported as errors.
291 files Limit the search to files. Default is to accept every type of
293 path.
294 links Limit the search to symbolic links. Default is to accept every
296 type of path.
297 directories
299 Limit the search to directories. Default is to accept every type
300 of path.
301 dirs An alias for directories.
303 all Accept all types of paths (default).
305 state? Returns the current state of the object as dictionary. The dic‐
307 tionary keys and their meanings are:
308 as Last setting made by as.
310 excluded
312 List of currently known exclusion patterns.
313 from Current source directory, set by from.
315 into Current destination directory, set by into (and aliases).
317 operation
319 Current operation to perform, set by copy, move, remove,
320 expand, or invoke.
321 recursive
323 Current recursion status. Set/unset by recursive and !re‐
324 cursive.
325 strict Current strictness. Set/unset by strict and !strict.
327 type Current path type limiter. Set by either files, directo‐
329 ries, links, or all.
330 as? Returns the current alias name.
332 excluded?
334 Returns the current set of exclusion patterns.
335 from? Returns the current source directory.
337 into? Returns the current destination directory.
339 operation?
341 Returns the current operation to perform.
342 recursive?
344 Returns the current recursion status.
345 strict?
347 Returns the current strictness.
348 type? Returns the current path type limiter.
350
352 The following examples assume that the variable F contains a reference
353 to a multi-file operation object.
354 $F do copy \
357 the *.dll \
358 from c:/TDK/PrivateOpenSSL/bin \
359 to [installdir_of tls]
360 $F do move \
364 the * \
365 from /sources \
366 into /scratch \
367 but not *.html
368 # Alternatively use 'except for *.html'.
370 $F do \
374 move \
375 the index \
376 from /sources \
377 into /scratch \
378 as pkgIndex.tcl
379 $F do \
383 remove \
384 the *.txt \
385 in /scratch
386 Note that the fact that most commands just modify the object state al‐
388 lows us to use more off forms as specifications instead of just nearly-
389 natural language sentences. For example the second example in this
390 section can re-arranged into:
391 $F do \
394 from /sources \
395 into /scratch \
396 but not *.html \
397 move \
398 the *
399 and the result is not only still a valid specification, but even stays
401 relatively readable.
402 Further note that the information collected by the commands but, ex‐
404 cept, and as is automatically reset after the associated the was exe‐
405 cuted. However no other state is reset in that manner, allowing the
406 user to avoid repetitions of unchanging information. For example the
407 second and third examples of this section can be merged and rewritten
408 into the equivalent:
409 $F do \
412 move \
413 the * \
414 from /sources \
415 into /scratch \
416 but not *.html not index \
417 the index \
418 as pkgIndex.tcl
419
422 This document, and the package it describes, will undoubtedly contain
423 bugs and other problems. Please report such in the category fileutil
424 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
425 also report any ideas for enhancements you may have for either package
426 and/or documentation.
427 When proposing code changes, please provide unified diffs, i.e the out‐
429 put of diff -u.
430 Note further that attachments are strongly preferred over inlined
432 patches. Attachments can be made by going to the Edit form of the
433 ticket immediately after its creation, and then using the left-most
434 button in the secondary navigation bar.
435
437 copy, file utilities, move, multi-file, remove
438
440 Programming tools
441tcllib 0.5.3 fileutil::multi::op(n)