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

NAME

8       fileutil - Procedures implementing some file utilities
9

SYNOPSIS

11       package require Tcl  8
12
13       package require fileutil  ?1.13.5?
14
15       ::fileutil::fullnormalize path
16
17       ::fileutil::test path codes ?msgvar? ?label?
18
19       ::fileutil::cat (?options? file)...
20
21       ::fileutil::writeFile ?options? file data
22
23       ::fileutil::appendToFile ?options? file data
24
25       ::fileutil::insertIntoFile ?options? file at data
26
27       ::fileutil::removeFromFile ?options? file at n
28
29       ::fileutil::replaceInFile ?options? file at n data
30
31       ::fileutil::updateInPlace ?options? file cmd
32
33       ::fileutil::fileType filename
34
35       ::fileutil::find ?basedir ?filtercmd??
36
37       ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
38
39       ::fileutil::foreachLine var filename cmd
40
41       ::fileutil::grep pattern ?files?
42
43       ::fileutil::install ?-m mode? source destination
44
45       ::fileutil::stripN path n
46
47       ::fileutil::stripPwd path
48
49       ::fileutil::stripPath prefix path
50
51       ::fileutil::jail jail path
52
53       ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
54
55       ::fileutil::tempdir
56
57       ::fileutil::tempdir path
58
59       ::fileutil::tempdirReset
60
61       ::fileutil::tempfile ?prefix?
62
63       ::fileutil::relative base dst
64
65       ::fileutil::relativeUrl base dst
66
67_________________________________________________________________
68

DESCRIPTION

70       This package provides implementations of standard unix utilities.
71
72       ::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
78       ::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
87              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
95
96              read   file readable
97
98              write  file writable
99
100              exists file exists
101
102              exec   file executable
103
104              file   file isfile
105
106              dir    file isdirectory
107
108       ::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
115              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
121              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
126       ::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
133       ::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
138       ::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
145              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
151              The command accepts the same options as ::fileutil::cat.
152
153       ::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
162              The command accepts the same options as ::fileutil::cat.
163
164       ::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
173              The command accepts the same options as ::fileutil::cat.
174
175       ::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
182              If the executed command throws an error the file is not changed.
183
184              The command accepts the same options as ::fileutil::cat.
185
186       ::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
201       ::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
212              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
218              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
222              Example:
223
224
225                  # 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
230
231       ::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
245       ::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
253       ::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
262       ::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
272       ::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
279       ::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
288       ::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
296       ::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
301              If  path  is  an  absolute  path  and  already within jail it is
302              returned unmodified.
303
304              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
311       ::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
319              This command is not available for Tcl versions less than 8.3.
320
321       ::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
326              [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
330              [2]    The directory named in the TMPDIR environment variable.
331
332              [3]    The directory named in the TEMP environment variable.
333
334              [4]    The directory named in the TMP environment variable.
335
336              [5]    A platform specific location:
337
338                     Windows
339                            "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried
340                            in that order.
341
342                     (classic) Macintosh
343                            The  TRASH_FOLDER  environment  variable  is used.
344                            This is most likely not correct.
345
346                     Unix   The directories "/tmp", "/var/tmp", and "/usr/tmp"
347                            are tried in that order.
348
349       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
353       ::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
359       ::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
363       ::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
370              The  code  was  taken from http://wiki.tcl.tk/772, attributed to
371              Igor Volobouev and anon.
372
373       ::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
381              Note:  The  processing  done  by this command is purely lexical.
382              Symbolic links are not taken into account.
383
384       ::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
390              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
395              Note: The processing done by this  command  is  purely  lexical.
396              Symbolic links are not taken into account.
397

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

406       cat, file utilities, grep, temp file, test, touch, type
407
408
409
410fileutil                            1.13.5                         fileutil(n)
Impressum