1fileutil::multi::op(n)          file utilities          fileutil::multi::op(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       fileutil::multi::op - Multi-file operation, scatter/gather
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require fileutil::multi::op  ?0.5.2?
14
15       package require wip  ?1.0?
16
17       ::fileutil::multi::op ?opName? ?word...?
18
19       opName option ?arg arg ...?
20
21       $opName do ?word...?
22
23       into directory
24
25       in directory
26
27       to directory
28
29       from directory
30
31       not pattern
32
33       for pattern
34
35       exclude pattern
36
37       but
38
39       except
40
41       as name
42
43       recursive
44
45       recursively
46
47       copy
48
49       move
50
51       remove
52
53       expand
54
55       invoke cmdprefix
56
57       reset
58
59       (
60
61       )
62
63       cd directory
64
65       up
66
67       for-windows
68
69       for-win
70
71       for-unix
72
73       the pattern
74
75       the-set varname
76
77       -> varname
78
79       strict
80
81       !strict
82
83       files
84
85       links
86
87       directories
88
89       dirs
90
91       all
92
93       state?
94
95       as?
96
97       excluded?
98
99       from?
100
101       into?
102
103       operation?
104
105       recursive?
106
107       strict?
108
109       type?
110
111_________________________________________________________________
112

DESCRIPTION

114       This package provides objects which are able to perform actions on mul‐
115       tiple files selected by glob patterns.
116
117       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

CLASS API

122       The main command of the package is:
123
124       ::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
130              opName option ?arg arg ...?
131                     Option  and  the args determine the exact behavior of the
132                     command.
133
134       If the string %AUTO% is used as the opName then the package will gener‐
135       ate a unique name on its own.
136
137       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

OBJECT API

142       The following methods are possible for multi-file operation objects:
143
144       $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
149              The  result  of  the  method is the result generated by the last
150              file command it executed.
151

FILE API

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
160       into directory
161              Specifies the destination directory for operations.
162
163       in directory
164              Alias for into.
165
166       to directory
167              Alias for into.
168
169       from directory
170              Specifies the source directory for operations.
171
172       not pattern
173              Specifies a glob pattern for paths to be excluded from the oper‐
174              ation.
175
176       for pattern
177              Alias for not.
178
179       exclude pattern
180              Alias for not.
181
182       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
188       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
194       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
197              operation.
198
199       recursive
200              Signals that file expansion should happen in the whole directory
201              hierarchy and not just the directory itself.
202
203       recursively
204              An alias for recursive.
205
206       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
210       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
214       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
218       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
222       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
229       reset  Forces  the  object into the ground state where all parts of the
230              configuration have default values.
231
232       (      Saves a copy of the current object state on a stack.
233
234       )      Takes the state at the top of the state stack and  restores  it,
235              i.e. makes it the new current object state.
236
237       cd directory
238              Changes the destination directory to the sub-directory directory
239              of the current destination.
240
241       up     Changes the destination directory to the parent directory of the
242              current destination.
243
244       for-windows
245              Checks  that  Windows is the current platform. Aborts processing
246              if not.
247
248       for-win
249              An alias for for-windows.
250
251       for-unix
252              Checks that Unix is the current platform. Aborts  processing  if
253              not.
254
255       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
258              actually  performs  the  specified operation. All the other com‐
259              mands only modified the object state to set  the  operation  up,
260              but di nothing else.
261
262              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
265              actions.  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
270              After  the  operation  has  been  performed the object state the
271              exclude patterns and the alias name, if specified, are reset  to
272              their default values (i.e. empty), but nothing else.
273
274       the-set varname
275              Like  the,  however  the  set  of  files to use is not specified
276              implicitly 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
280       -> varname
281              Saves the set of files from the last expansion into  the  speci‐
282              fied variable.
283
284       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
288       !strict
289              Complement  of  strict. A missing destination directory or empty
290              expansion are not reported as errors.
291
292       files  Limit the search to files. Default is to accept  every  type  of
293              path.
294
295       links  Limit  the  search to symbolic links. Default is to accept every
296              type of path.
297
298       directories
299              Limit the search to directories. Default is to accept every type
300              of path.
301
302       dirs   An alias for directories.
303
304       all    Accept all types of paths (default).
305
306       state? Returns  the current state of the object as dictionary. The dic‐
307              tionary keys and their meanings are:
308
309              as     Last setting made by as.
310
311              excluded
312                     List of currently known exclusion patterns.
313
314              from   Current source directory, set by from.
315
316              into   Current destination directory, set by into (and aliases).
317
318              operation
319                     Current operation to perform, set by copy, move,  remove,
320                     expand, or invoke.
321
322              recursive
323                     Current  recursion  status.  Set/unset  by  recursive and
324                     !recursive.
325
326              strict Current strictness. Set/unset by strict and !strict.
327
328              type   Current path type limiter. Set by either files,  directo‐
329                     ries, links, or all.
330
331       as?    Returns the current alias name.
332
333       excluded?
334              Returns the current set of exclusion patterns.
335
336       from?  Returns the current source directory.
337
338       into?  Returns the current destination directory.
339
340       operation?
341              Returns the current operation to perform.
342
343       recursive?
344              Returns the current recursion status.
345
346       strict?
347              Returns the current strictness.
348
349       type?  Returns the current path type limiter.
350

EXAMPLES

352       The  following examples assume that the variable F contains a reference
353       to a multi-file operation object.
354
355           $F do copy                       \\
356            the  *.dll                    \\
357            from c:/TDK/PrivateOpenSSL/bin \\
358            to   [installdir_of tls]
359
360
361           $F do move      \\
362            the  *       \\
363            from /sources \\
364            into /scratch  \\
365            but not *.html
366
367           # Alternatively use 'except for *.html'.
368
369
370           $F do           \\
371            move         \\
372            the  index    \\
373            from /sources  \\
374            into /scratch   \\
375            as   pkgIndex.tcl
376
377
378           $F do         \\
379            remove     \\
380            the *.txt  \\
381            in /scratch
382
383       Note that the fact that most commands  just  modify  the  object  state
384       allows  us  to  use  more  off  forms as specifications instead of just
385       nearly-natural language sentences.  For example the second  example  in
386       this section can re-arranged into:
387
388           $F do            \\
389            from /sources \\
390            into /scratch  \\
391            but not *.html \\
392            move           \\
393            the  *
394
395       and  the result is not only still a valid specification, but even stays
396       relatively readable.
397
398       Further note that  the  information  collected  by  the  commands  but,
399       except, and as is automatically reset after the associated the was exe‐
400       cuted. However no other state is reset in  that  manner,  allowing  the
401       user  to  avoid  repetitions of unchanging information. For example the
402       second and third examples of this section can be merged  and  rewritten
403       into the equivalent:
404
405       $F do                   \\
406           move                 \\
407           the  *                \\
408           from /sources          \\
409           into /scratch           \\
410           but not *.html not index \\
411           the  index               \\
412           as   pkgIndex.tcl
413
414

BUGS, IDEAS, FEEDBACK

416       This  document,  and the package it describes, will undoubtedly contain
417       bugs and other problems.  Please report such in the  category  fileutil
418       of       the       Tcllib       SF       Trackers       [http://source
419       forge.net/tracker/?group_id=12883].  Please also report any  ideas  for
420       enhancements you may have for either package and/or documentation.
421

KEYWORDS

423       copy, file utilities, move, multi-file, remove
424
425
426
427fileutil                             0.5.2              fileutil::multi::op(n)
Impressum