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