class file

superclass(es) object
subclass(es) -
description This class can be used for creating, reading and writing of binary and text files. Like all classes in TPWin this class is not part of the ISO prolog standard.
file The class declaration is located in the file os.txt. This file is included by win.txt

tasks

File types

During the opening of a file the file mode, binary or text, must be specified. For text files certain characters are replaced by other characters and for binary files no characters are translated. A newline character is converted to a carriage return/linefeed character pair and vice versa if the file is opened as a text file. There may not be a one-to-one relationship between the characters that are written (or read) and those in the external file for a text file. The atoms for setting the type of a file are: binary or text.

Opening files

Another important parameter for opening a file determines if a file may be created if it doesn't exist, if writing can occur at any position in a file or that all characters written to the file are appended. The four possible atomic values for this parameter are: normal, append, create and create_append.

normal : the file must exist else it cannot be opened and writing can occur at any position.
append : the file must exist and all characters written are appended to the file.
create : the file may be created if it doesn't exist and writing can occur at any position.
create_append : the file may be created and all characters written are appended to the file.

If a file is opened by the openRead/4 method then no writing to the file is allowed. If reading is not allowed then openWrite/4 must be used, else if reading and writing are both allowed use the method openReadWrite/4 to open a file. A temporary file can also be opened, such a file is deleted if the file is closed, the method openTemporary/1 creates such a file. To create a file with a unique name the method openUniqueFile/4 can be used. To close a file the class instance can be deleted or the method close/1 can be called.

Using the file class

To get various parts of the filename use the methods: drive/1, folder/1, file/1 and extension/1. With the methods isReadOnly/1 and isHidden/1 the read-only and hidden attributes of a file can be queried.

To write/read data to and from the file the methods readString/3, writeString/3 and writeString/2 can be used. The position of reading and writing of data is determined by the file pointer, the position of the file pointer can be queried by the method curPos/1, the position of the file pointer can be changed by the methods: rewind/0, seek/3, gotoBegin/1, gotoEnd/1, goBack/2 and goForward/2. If data is written or appended to a file then the file may grow in size, to make a file smaller the method changeSize/1 can be used. The method size/1 returns the number of bytes in a file.

It is also possible to rename a file or for instance rename just the extension of a file, the methods: rename/3, renameFolder/3, renameFile/3 and renameExtension/3 can be used for renaming. A file being renamed may not be open in any process, use the method putFileName/1 to set the 'old' filename before renaming without opening the file.

To copy all the data from one file to another file there is the method copyAllFrom/2, it copies all data from one file class instance to another file class instance if both files are open.

methods

openRead(Name, Mode, HowTo, Output)

func Open a file for reading, writing to the file is not allowed. The location of the file is the value of the variable Name and the Mode parameter determines if the file is opened in binary or text mode. The value of the parameter HowTo determines how the file is opened.
pre The variable Name must contain a string value, the parameter Mode must contain one of the following two atomic values: binary or text. The parameter HowTo must contain one of the following predefined atoms: normal, append, create or create_append.
post If the file was opened (or created if allowed) then was true assigned to the variable Output, else was false assigned.

openWrite(Name, Mode, HowTo, Output)

func Open a file for writing, reading to the file is not allowed. The location of the file is the value of the variable Name and the Mode parameter determines if the file is opened in binary or text mode. The value of the parameter HowTo determines how the file is opened.
pre The variable Name must contain a string value, the parameter Mode must contain one of the following two atomic values: binary or text. The parameter HowTo must contain one of the following predefined atoms: normal, append, create or create_append.
post If the file was opened (or created if allowed) then was true assigned to the variable Output, else was false assigned.

openReadWrite(Name, Mode, HowTo, Output)

func Open a file for reading and writing. The location of the file is the value of the variable Name and the Mode parameter determines if the file is opened in binary or text mode. The value of the parameter HowTo determines how the file is opened.
pre The variable Name must contain a string value, the parameter Mode must contain one of the following two atomic values: binary or text. The parameter HowTo must contain one of the following predefined atoms: normal, append, create or create_append.
post If the file was opened (or created if allowed) then was true assigned to the variable Output, else was false assigned.

openTemporary(Output)

func Open a temporary file for reading and writing. The file exists until it is closed, after the file was closed it is automatically deleted. The file is opened in binary mode.
pre TRUE
post If the temporary file was created then was true assigned to the variable Output, else was false assigned.

openUniqueFile(Path, Mode, HowTo, Output)

func Open a file with a unique name, the value of the Path variable is used to append an unique name to it. The folder of the file is the value of the variable Path and the Mode parameter determines if the file is opened in binary or text mode. The value of the parameter HowTo determines how the file is opened.
For instance: if the value of Path is 'c:\temp\' then the file 'c:\temp\tmp1.$$$' could be created.
pre The variable Path must contain a string value, the parameter Mode must contain one of the following two atomic values: binary or text. The parameter HowTo must contain one of the following predefined atoms: normal, append, create or create_append.
post If the file was created then was true assigned to the variable Output, else was false assigned.

putFileName(Name)

func Set the name of the file instance. The file is not opened.
pre The variable Name must contain a string value
post The value of the parameter was stored as the filename. If a file is being renamed then it may not be open
arrow.gif (1632 bytes) Renaming a file will fail if the file is open in any process, so this method can be used to set the 'old' name of the file (before renaming) without opening the file.

isOpen(Output)

func Determine if a file is open or not.
pre TRUE
post If the file was open then was true assigned to the variable Output, else was false assigned.

close

func Close the file.
pre TRUE
post The file was closed.

name(Output)

func Get the name of the file.
pre TRUE
post The complete name of the file was assigned to the variable Output.

drive(Output)

func Get the drive part of the name of the file. If the filename is 'c:\temp\test1.txt' then is 'c:' assigned to Output.
pre TRUE
post The drive part of the filename was assigned to the variable Output.

folder(Output)

func Get the folder part of the name of the file. If the filename is 'c:\temp\test1.txt' then is '\temp\' assigned to Output.
pre TRUE
post The folder part of the filename was assigned to the variable Output.

file(Output)

func Get the file part of the name of the file. If the filename is 'c:\temp\test1.txt' then is 'test1' assigned to Output.
pre TRUE
post The file part of the filename was assigned to the variable Output.

extension(Output)

func Get the extension part of the name of the file. If the filename is 'c:\temp\test1.txt' then is '.txt' assigned to Output.
pre TRUE
post The extension part of the filename was assigned to the variable Output.

delete(Output)

func Close and delete the open file.
pre TRUE
post If the file was successfully closed and deleted then was true assigned to the variable Output, else was false assigned.

isReadOnly(Output)

func Determine if the file is read-only or not.
pre TRUE
post If the file is read-only then was true assigned to the variable Output, else was false assigned.

isHidden(Output)

func Determine if the file is hidden or not.
pre TRUE
post If the file is hidden then was true assigned to the variable Output, else was false assigned.

readString(Num, Output, OutputString)

func Read a number of characters from the open file, the number of characters to read is determined by the contents of the variable Num. The characters read are put into the variable OutputString.
pre The variable Num must contain a positive integer value.
post If the characters were read successfully then was true assigned to the variable Output, else was false assigned. The characters read were assigned to the variable OutputString.

writeString(String, Num, Output)

func Write a number of characters of the string to the open file, the number of characters to write is determined by the contents of the variable Num. The characters to write must be in the variable String.
pre The variable String must contain a string value and the variable Num must contain a positive integer value.
post If the characters were written successfully then was true assigned to the variable Output, else was false assigned.

writeString(String, Output)

func Write a string to the open file. The characters to write must be in the variable String.
pre The variable String must contain a string value.
post If the characters were written successfully then was true assigned to the variable Output, else was false assigned.

size(Output)

func Determine the size of the file.
pre TRUE
post The number of bytes of the file was assigned to the variable Output.

changeSize(NewSize)

func Change the size of the file. The new size of the file must be specified in bytes. This method is very useful to make a file smaller.
pre The parameter NewSize must contain a positive integer.
post The number of bytes in the file is equal to NewSize.

rewind

func Reposition the file pointers to the beginning of the file.
pre TRUE
post The file pointers are at the beginning of the file.

seek(Offset, FilePos, Output)

func Reposition the file pointer of the file. The value of the parameter FilePos determines the relative position from where the file pointer is repositioned. The FilePos parameter can be one of the following values: begin, current or end. The Offset parameter determines the number of bytes the file pointer is moved, for instance:

X is -4,
seek(X, end, true),

These two lines of code move the filepointer 4 bytes in front of the end-of-file.
pre The parameter Offset must contain a positive integer and the value of the variable FilePos must be one of the following predefined atoms: begin, current or end.
post If the file pointer was moved then was true assigned to the variable Output, else was false assigned.

gotoBegin(Output)

func Move the file pointer to the beginning of the file.
pre TRUE
post If the file pointer was moved then was true assigned to the variable Output, else was false assigned.

gotoEnd(Output)

func Move the file pointer to the end of the file.
pre TRUE
post If the file pointer was moved then was true assigned to the variable Output, else was false assigned.

goBack(Num, Output)

func Move the file pointer a number of bytes back from the current position.
pre The parameter Offset must contain a positive integer.
post If the file pointer was moved back then was true assigned to the variable Output, else was false assigned.

goForward(Num, Output)

func Move the file pointer a number of bytes forward from the current position.
pre The parameter Offset must contain a positive integer.
post If the file pointer was moved forward then was true assigned to the variable Output, else was false assigned.

curPos(Output)

func Get the current position of the file pointer.
pre TRUE
post The current position of the file pointer was assigned to variable Output.

flush(Output)

func Flush the read and write buffers of the file. This is only necessary if large amounts of data are read/written and the output device is very slow.
pre TRUE
post The read and write buffers were flushed and are empty after this method call. If true was assigned then flushing the buffers was successful else was false assigned to Output.

rename(NewName, Overwrite, Output)

func Rename the current file, if there is a file with the same name as the renamed file will have then Overwrite must be true to allow overwriting the destination file. If this is not allowed then Overwrite must contain the value false. It is not allowed to use a different drive specification in the new name of the file. The file may not be open in any process.
pre The variable NewName must contain a string value and Overwrite must contain true or false.
post If renaming the file was successful then was true assigned to Output, else was false assigned.
arrow.gif (1632 bytes) see also putFileName/1

renameFolder(NewName, Overwrite, Output)

func Rename the current file, only the folder part of the filename must be specified. If there is a file with the same name as the renamed file will have then Overwrite must be true to allow overwriting the destination file. If this is not allowed then Overwrite must contain the value false. The file may not be open in any process.
pre The variable NewName must contain a string value and Overwrite must contain true or false.
post If renaming the file was successful then was true assigned to Output, else was false assigned.
arrow.gif (1632 bytes) see also putFileName/1

renameFile(NewName, Overwrite, Output)

func Rename the current file, only the file part of the filename must be specified. If there is a file with the same name as the renamed file will have then Overwrite must be true to allow overwriting the destination file. If this is not allowed then Overwrite must contain the value false. The file may not be open in any process.
pre The variable NewName must contain a string value and Overwrite must contain true or false.
post If renaming the file was successful then was true assigned to Output, else was false assigned.
arrow.gif (1632 bytes) see also putFileName/1

renameExtension(NewName, Overwrite, Output)

func Rename the current file, only the extension part of the filename must be specified. If there is a file with the same name as the renamed file will have then Overwrite must be true to allow overwriting the destination file. If this is not allowed then Overwrite must contain the value false. The file may not be open in any process.
pre The variable NewName must contain a string value and Overwrite must contain true or false.
post If renaming the file was successful then was true assigned to Output, else was false assigned.
arrow.gif (1632 bytes) see also putFileName/1

copyAllFrom(File, Output)

func Copy all the bytes from the parameter File to the file instance for which the method was called.
pre The variable File must refer to an instance of the class file and that file instance must be open.
post If copying the entire file was successful then true was assigned to Output, else was false assigned.