File Handling
Frag provides a number of commands for file handling. The File object offers a number of methods
for manipulating files, as well as a number of class object methods. All file IO commands are
loaded into the Frag default configuration.
File is a class that is used to create file objects, which can be used as file handles.
File provides a number of other class object methods:
File constructFileName ? file name elements ... ?
constructFileName builds a file name from file name elements that uses the
file separator of the operating system.
The following code:
puts [File constructFileName a b]
prints the same like:
puts "[File getSeparator]a[File getSeparator]b"
For instance under UNIX it prints: /a/b
File getSeparator
getSeparator returns the file separator of the operating system.
The following code return "\" under Windows and "/" under Linux
puts [File getSeparator]
File getUserDir
Returns the current user directory.
The following code prints the current user directory.
puts [File getUserDir]
File is a class that is used to create file objects, which can be used as file handles.
File provides a number methods for its instances.
<fileInstance> append <content>
append appends the (string) content of content to the file.
The following code creates a file and writes ABC into
it. Next, it appends "DEF" to the file. Finally it reads the file.
The result should hence be ABCDEF.
set f1 [File create -name __test_a1]
$f1 write "ABC"
$f1 append DEF
puts [$f1 read]
<fileInstance> copyDirTo <targetFileName>
copyDirTo tries to copy a directory to targetFileName. copyDirTo
returns true upon success,
or false otherwise.
The following code creates a new directory and copies it to __test_a2.
set f1 [File create -name __test_a1 -mkdir]
$f1 copyTo __test_a2
<fileInstance> copyTo <targetFileName>
copyTo tries to copy a file to targetFileName. copyTo
returns true upon success,
or false otherwise.
The following code creates a new file and copies it to __test_a2.
set f1 [File create -name __test_a1 -createNewFile]
$f1 copyTo __test_a2
<fileInstance> createNewFile
createNewFile tries to create a file with the file name given to the fileInstancecreateNewFile returns true if the file creation was successful,
or false if not.
The following code prints 1 0 because it is tried to created the same file name
twice. The first time it succeeds, if the file does not exist, the second time it does
not succeed, because this time the file exists.
set f1 [File create -name __test_a1]
set f2 [File create -name __test_a1]
puts [list build [$f1 createNewFile] [$f2 createNewFile]]
<fileInstance> delete
delete tries to delete a file. delete returns true if the
file deletion was successful,
or false if not.
The following code prints true false because it is tried to delete the same file name
twice. The first time it succeeds; the second time it does
not succeed, because this time the file is already deleted.
set f1 [File create -name __test_a1]
puts [list build [$f1 delete] [$f1 delete]]
<fileInstance> deleteDir
deleteDir tries to delete a directory. deleteDir
returns true if the
directory deletion was successful,
or false if not.
The following code prints true false because it is tried to delete the same directory name
twice. The first time it succeeds; the second time it does
not succeed, because this time the directory is already deleted.
set f1 [File create -name __test_a1]
puts [list build [$f1 deleteDir] [$f1 deleteDir]]
<fileInstance> exists
exists returns true if a file handle points to file that exists,
or false if not.
The following code creates a file handle to the current user directory, which should exist,
and hence the code prints true.
puts [[File create -name [File getUserDir]] exists]
<fileInstance> getAbsoluteFile
getAbsoluteFile returns the absolute file name, using the separators of the
operating system.
The following code creates a file with the name a1 and prints the absolute file name.
File create a1 -name a1
puts [a1 getAbsoluteFile]
<fileInstance> getCanonicalFile
getCanonicalFile does the same as getAbsoluteFile but in addition it canonicalizes
the file name, so that specifics of the file part in the file names are not shown. That is,
the file names are "absolute and unique". Specifics of file names pointing to the same
file like "a1" and "./a1" are not shown.
The following code shows two "absolute and unique" file names, which are identical:
puts [[File create -name ./a1] getCanonicalFile]
puts [[File create -name a1] getCanonicalFile]
<fileInstance> getParent
getParent gets the parent directory path of a file name.
The following code shows that getParent of a plain file name just created
equals File getUserDir, because the file gets created in the current user directory.
File create a1 -name a1
a1 name [a1 getAbsoluteFile]
puts "[a1 getParent] equals [File getUserDir]"
<fileInstance> isDirectory
isDirectory returns true if a file handle points to a directory,
or false if not.
The following code prints true because it creates a file handle to the user directory,
which is a directory.
puts [[File create -name [File getUserDir]] isDirectory]
<fileInstance> length
length returns the length of a file.
The following code returns 0 because the length of a new file is always 0.
set f1 [File create -name __test_a1]
$f1 length
<fileInstance> listDir
listDir lists the contents in a directory. Note that
there is no particular ordering guaranteed in the resulting
list. If needed, consider using list sort.
The following code lists the files (including directory names)
in the current user directory.
puts [[File create -name [File getUserDir]] listDir]
<fileInstance> mkdir
mkdir tries to create a directory with the file name given to the fileInstancemkdir returns true if the creation was successful,
or false if not.
The following code prints true false because it is tried to created the directory with
the same file name
twice. The first time it succeeds, if the file does not exist; the second time it does
not succeed, because this time the directory exists.
set f1 [File create -name __test_a1]
set f2 [File create -name __test_a1]
puts [list build [$f1 mkdir] [$f2 mkdir]]
<fileInstance> mkdirs
mkdirs tries to create a directory with the file name given to the fileInstancemkdirs returns true if the creation was successful,
or false if not. In contrast to mkdir, mkdir create the directory
including any necessary but nonexistent parent directories.
The following code prints true false because it is tried to created the directory with
the same file name
twice. The first time it succeeds, if the file does not exist; the second time it does
not succeed, because this time the directory exists. Please note that the parent directories
are created during creation of y.
set f1 [File create -name __test_a1/x/y]
set f2 [File create -name __test_a1/x/y]
puts [list build [$f1 mkdir] [$f2 mkdir]]
<fileInstance> name ?fileName?
name must be used upon file creation to specify the file name of a file handle.
If the fileName argument is omitted, the file name is read.
The following code name to specify a file name upon creation, then it reads it,
changes it, and reads it again. The result is a1 a2.
File create a1 -name a1
puts [a1 name]
a1 name a2
puts [a1 name]
<fileInstance> read ?encoding?
read reads the content of a file and returns it (as a string). Optionally, the
encoding can be given, such as "8859_1" or "UTF8".
The following code creates a file and writes ABC into
it. Next, it reads the file. The result should hence be ABC.
set f1 [File create -name __test_a1]
$f1 write "ABC"
puts [$f1 read]
<fileInstance> renameTo <targetFileName>
renameTo tries to rename a file to targetFileName. renameTo
returns true upon success,
or false otherwise.
The following code creates a new file and renames it to __test_a2.
set f1 [File create -name __test_a1 -createNewFile]
$f1 renameTo __test_a2
<fileInstance> write <content> ?encoding?'
write writes the (string) content of content into the file. Optionally, the
encoding can be given, such as "8859_1" or "UTF8".
The following code creates a file and writes ABC into
it. Next, it reads the file. The result should hence be ABC.
set f1 [File create -name __test_a1]
$f1 write "ABC"
puts [$f1 read]
