1fileutil(n) file utilities fileutil(n)
2______________________________________________________________________________
6
8 fileutil - Procedures implementing some file utilities
9
11 package require Tcl 8
12 package require fileutil ?1.13.5?
14 ::fileutil::fullnormalize path
16 ::fileutil::test path codes ?msgvar? ?label?
18 ::fileutil::cat (?options? file)...
20 ::fileutil::writeFile ?options? file data
22 ::fileutil::appendToFile ?options? file data
24 ::fileutil::insertIntoFile ?options? file at data
26 ::fileutil::removeFromFile ?options? file at n
28 ::fileutil::replaceInFile ?options? file at n data
30 ::fileutil::updateInPlace ?options? file cmd
32 ::fileutil::fileType filename
34 ::fileutil::find ?basedir ?filtercmd??
36 ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
38 ::fileutil::foreachLine var filename cmd
40 ::fileutil::grep pattern ?files?
42 ::fileutil::install ?-m mode? source destination
44 ::fileutil::stripN path n
46 ::fileutil::stripPwd path
48 ::fileutil::stripPath prefix path
50 ::fileutil::jail jail path
52 ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
54 ::fileutil::tempdir
56 ::fileutil::tempdir path
58 ::fileutil::tempdirReset
60 ::fileutil::tempfile ?prefix?
62 ::fileutil::relative base dst
64 ::fileutil::relativeUrl base dst
66_________________________________________________________________
68
70 This package provides implementations of standard unix utilities.
71 ::fileutil::fullnormalize path
73 This command resolves all symbolic links in the path and returns
74 the changed path as its result. In contrast to the builtin file
75 normalize this command resolves a symbolic link in the last ele‐
76 ment of the path as well.
77 ::fileutil::test path codes ?msgvar? ?label?
79 A command for the testing of several properties of a path. The
80 properties to test for are specified in codes, either as a list
81 of keywords describing the properties, or as a string where each
82 letter is a shorthand for a property to test. The recognized
83 keywords, shorthands, and associated properties are shown in the
84 list below. The tests are executed in the order given to the
85 command.
86 The result of the command is a boolean value. It will be true if
88 and only if the path passes all the specified tests. In the
89 case of the path not passing one or more test the first failing
90 test will leave a message in the variable referenced by msgvar,
91 if such is specified. The message will be prefixed with label,
92 if it is specified. Note that the variabled referenced by msg‐
93 var is not touched at all if all the tests pass.
94 read file readable
97 write file writable
99 exists file exists
101 exec file executable
103 file file isfile
105 dir file isdirectory
107 ::fileutil::cat (?options? file)...
109 A tcl implementation of the UNIX cat command. Returns the con‐
110 tents of the specified file(s). The arguments are files to read,
111 with interspersed options configuring the process. If there are
112 problems reading any of the files, an error will occur, and no
113 data will be returned.
114 The options accepted are -encoding, -translation, -eofchar, and
116 --. With the exception of the last all options take a single
117 value as argument, as specified by the tcl builtin command fcon‐
118 figure. The -- has to be used to terminate option processing
119 before a file if that file's name begins with a dash.
120 Each file can have its own set of options coming before it, and
122 for anything not specified directly the defaults are inherited
123 from the options of the previous file. The first file inherits
124 the system default for unspecified options.
125 ::fileutil::writeFile ?options? file data
127 The command replaces the current contents of the specified file
128 with data, with the process configured by the options. The com‐
129 mand accepts the same options as ::fileutil::cat. The specifica‐
130 tion of a non-existent file is legal and causes the command to
131 create the file (and all required but missing directories).
132 ::fileutil::appendToFile ?options? file data
134 This command is like ::fileutil::writeFile, except that the pre‐
135 vious contents of file are not replaced, but appended to. The
136 command accepts the same options as ::fileutil::cat
137 ::fileutil::insertIntoFile ?options? file at data
139 This comment is similar to ::fileutil::appendToFile, except that
140 the new data is not appended at the end, but inserted at a spec‐
141 ified location within the file. In further contrast this command
142 has to be given the path to an existing file. It will not create
143 a missing file, but throw an error instead.
144 The specified location at has to be an integer number in the
146 range 0 ... [file size file]. 0 will cause insertion of the new
147 data before the first character of the existing content, whereas
148 [file size file] causes insertion after the last character of
149 the existing content, i.e. appending.
150 The command accepts the same options as ::fileutil::cat.
152 ::fileutil::removeFromFile ?options? file at n
154 This command is the complement to ::fileutil::insertIntoFile,
155 removing n characters from the file, starting at location at.
156 The specified location at has to be an integer number in the
157 range 0 ... [file size file] - n. 0 will cause the removal of
158 the new data to start with the first character of the existing
159 content, whereas [file size file] - n causes the removal of the
160 tail of the existing content, i.e. the truncation of the file.
161 The command accepts the same options as ::fileutil::cat.
163 ::fileutil::replaceInFile ?options? file at n data
165 This command is a combination of ::fileutil::removeFromFile and
166 ::fileutil::insertIntoFile. It first removes the part of the
167 contents specified by the arguments at and n, and then inserts
168 data at the given location, effectively replacing the removed by
169 content with data. All constraints imposed on at and n by
170 ::fileutil::removeFromFile and ::fileutil::insertIntoFile are
171 obeyed.
172 The command accepts the same options as ::fileutil::cat.
174 ::fileutil::updateInPlace ?options? file cmd
176 This command can be seen as the generic core functionality of
177 ::fileutil::replaceInFile. It first reads the contents of the
178 specified file, then runs the command prefix cmd with that data
179 appended to it, and at last writes the result of that invokation
180 back as the new contents of the file.
181 If the executed command throws an error the file is not changed.
183 The command accepts the same options as ::fileutil::cat.
185 ::fileutil::fileType filename
187 An implementation of the UNIX file command, which uses various
188 heuristics to guess the type of a file. Returns a list specify‐
189 ing as much type information as can be determined about the
190 file, from most general (eg, "binary" or "text") to most spe‐
191 cific (eg, "gif"). For example, the return value for a GIF file
192 would be "binary graphic gif". The command will detect the fol‐
193 lowing types of files: directory, empty, binary, text, script
194 (with interpreter), executable elf, executable dos, executable
195 ne, executable pe, graphic gif, graphic jpeg, graphic png,
196 graphic tiff, graphic bitmap, html, xml (with doctype if avail‐
197 able), message pgp, binary pdf, text ps, text eps, binary grav‐
198 ity_wave_data_frame, compressed bzip, compressed gzip, com‐
199 pressed zip, compressed tar, audio wave, audio mpeg, and link.
200 ::fileutil::find ?basedir ?filtercmd??
202 An implementation of the unix command find. Adapted from the
203 Tcler's Wiki. Takes at most two arguments, the path to the
204 directory to start searching from and a command to use to evalu‐
205 ate interest in each file. The path defaults to ".", i.e. the
206 current directory. The command defaults to the empty string,
207 which means that all files are of interest. The command takes
208 care not to lose itself in infinite loops upon encountering cir‐
209 cular link structures. The result of the command is a list con‐
210 taining the paths to the interesting files.
211 The filtercmd, if specified, is interpreted as a command prefix
213 and one argument is added to it, the name of the file or direc‐
214 tory find is currently looking at. Note that this name is not
215 fully qualified. It has to be joined it with the result of pwd
216 to get an absolute filename.
217 The result of filtercmd is a boolean value that indicates if the
219 current file should be included in the list of interesting
220 files.
221 Example:
223 # find .tcl files
226 package require fileutil
227 proc is_tcl {name} {return [string match *.tcl $name]}
228 set tcl_files [fileutil::find . is_tcl]
229 ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
232 This command is based upon the TclX command recursive_glob,
233 except that it doesn't allow recursion over more than one direc‐
234 tory at a time. It uses ::fileutil::find internally and is thus
235 able to and does follow symbolic links, something the TclX com‐
236 mand does not do. First argument is the directory to start the
237 search in, second argument is a list of patterns. The command
238 returns a list of all files reachable through basedir whose
239 names match at least one of the patterns. The options before the
240 pattern-list determine the style of matching, either regexp or
241 glob. glob-style matching is the default if no options are
242 given. Usage of the option -- stops option processing. This
243 allows the use of a leading '-' in the patterns.
244 ::fileutil::foreachLine var filename cmd
246 The command reads the file filename and executes the script cmd
247 for every line in the file. During the execution of the script
248 the variable var is set to the contents of the current line. The
249 return value of this command is the result of the last invoca‐
250 tion of the script cmd or the empty string if the file was
251 empty.
252 ::fileutil::grep pattern ?files?
254 Implementation of grep. Adapted from the Tcler's Wiki. The first
255 argument defines the pattern to search for. This is followed by
256 a list of files to search through. The list is optional and
257 stdin will be used if it is missing. The result of the proce‐
258 dures is a list containing the matches. Each match is a single
259 element of the list and contains filename, number and contents
260 of the matching line, separated by a colons.
261 ::fileutil::install ?-m mode? source destination
263 The install command is similar in functionality to the install
264 command found on many unix systems, or the shell script distrib‐
265 uted with many source distributions (unix/install-sh in the Tcl
266 sources, for example). It copies source, which can be either a
267 file or directory to destination, which should be a directory,
268 unless source is also a single file. The ?-m? option lets the
269 user specify a unix-style mode (either octal or symbolic - see
270 file attributes.
271 ::fileutil::stripN path n
273 Removes the first n elements from the specified path and returns
274 the modified path. If n is greater than the number of components
275 in path an empty string is returned. The number of components in
276 a given path may be determined by performing llength on the list
277 returned by file split.
278 ::fileutil::stripPwd path
280 If, and only if the path is inside of the directory returned by
281 [pwd] (or the current working directory itself) it is made rela‐
282 tive to that directory. In other words, the current working
283 directory is stripped from the path. The possibly modified path
284 is returned as the result of the command. If the current working
285 directory itself was specified for path the result is the string
286 ".".
287 ::fileutil::stripPath prefix path
289 If, and only of the path is inside of the directory "prefix" (or
290 the prefix directory itself) it is made relative to that direc‐
291 tory. In other words, the prefix directory is stripped from the
292 path. The possibly modified path is returned as the result of
293 the command. If the prefix directory itself was specified for
294 path the result is the string ".".
295 ::fileutil::jail jail path
297 This command ensures that the path is not escaping the directory
298 jail. It always returns an absolute path derived from path which
299 is within jail.
300 If path is an absolute path and already within jail it is
302 returned unmodified.
303 An absolute path outside of jail is stripped of its root element
305 and then put into the jail by prefixing it with it. The same
306 happens if path is relative, except that nothing is stripped of
307 it. Before adding the jail prefix the path is lexically normal‐
308 ized to prevent the caller from using .. segments in path to
309 escape the jail.
310 ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
312 Implementation of touch. Alter the atime and mtime of the speci‐
313 fied files. If -c, do not create files if they do not already
314 exist. If -r, use the atime and mtime from ref_file. If -t, use
315 the integer clock value time. It is illegal to specify both -r
316 and -t. If -a, only change the atime. If -m, only change the
317 mtime.
318 This command is not available for Tcl versions less than 8.3.
320 ::fileutil::tempdir
322 The command returns the path of a directory where the caller can
323 place temporary files, such as "/tmp" on Unix systems. The algo‐
324 rithm we use to find the correct directory is as follows:
325 [1] The directory set by an invokation of ::fileutil::tempdir
327 with an argument. If this is present it is tried exclu‐
328 sively and none of the following item are tried.
329 [2] The directory named in the TMPDIR environment variable.
331 [3] The directory named in the TEMP environment variable.
333 [4] The directory named in the TMP environment variable.
335 [5] A platform specific location:
337 Windows
339 "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried
340 in that order.
341 (classic) Macintosh
343 The TRASH_FOLDER environment variable is used.
344 This is most likely not correct.
345 Unix The directories "/tmp", "/var/tmp", and "/usr/tmp"
347 are tried in that order.
348 The algorithm utilized is mainly that used in the Python standard
350 library. The exception is the first item, the ability to have the
351 search overridden by a user-specified directory.
352 ::fileutil::tempdir path
354 In this mode the command sets the path as the first and only
355 directory to try as a temp. directory. See the previous item for
356 the use of the set directory. The command returns the empty
357 string.
358 ::fileutil::tempdirReset
360 Invoking this command clears the information set by the last
361 call of [::fileutil::tempdir path]. See the last item too.
362 ::fileutil::tempfile ?prefix?
364 The command generates a temporary file name suitable for writing
365 to, and the associated file. The file name will be unique, and
366 the file will be writable and contained in the appropriate sys‐
367 tem specific temp directory. The name of the file will be
368 returned as the result of the command.
369 The code was taken from http://wiki.tcl.tk/772, attributed to
371 Igor Volobouev and anon.
372 ::fileutil::relative base dst
374 This command takes two directory paths, both either absolute or
375 relative and computes the path of dst relative to base. This
376 relative path is returned as the result of the command. As
377 implied in the previous sentence, the command is not able to
378 compute this relationship between the arguments if one of the
379 paths is absolute and the other relative.
380 Note: The processing done by this command is purely lexical.
382 Symbolic links are not taken into account.
383 ::fileutil::relativeUrl base dst
385 This command takes two file paths, both either absolute or rela‐
386 tive and computes the path of dst relative to base, as seen from
387 inside of the base. This is the algorithm how a browser resolves
388 a relative link found in the currently shown file.
389 The computed relative path is returned as the result of the com‐
391 mand. As implied in the previous sentence, the command is not
392 able to compute this relationship between the arguments if one
393 of the paths is absolute and the other relative.
394 Note: The processing done by this command is purely lexical.
396 Symbolic links are not taken into account.
397
399 This document, and the package it describes, will undoubtedly contain
400 bugs and other problems. Please report such in the category fileutil
401 of the Tcllib SF Trackers [http://source‐
402 forge.net/tracker/?group_id=12883]. Please also report any ideas for
403 enhancements you may have for either package and/or documentation.
404
406 cat, file utilities, grep, temp file, test, touch, type
407fileutil 1.13.5 fileutil(n)