Difference between revisions of "File Handling In Pascal"

From Lazarus wiki
Jump to navigationJump to search
({$mode objfpc})
 
(93 intermediate revisions by 25 users not shown)
Line 1: Line 1:
==File handling==
+
{{File Handling In Pascal}}
  
Something most programmers need to know how to do is work with files. Files can be used to save user settings, error logs, and more. Here i am going to teach you how to work with basic text files.
+
==Overview==
  
===About files===
+
Something every programmer needs to know is how to work with files. Files are used to persist data i.e. store data in such a way that it can be retrieved at a later time, without having to recreate it. Files can be used to store user settings, error logs, measurement or calculation results, and more. This page explains the basics of file handling.
  
When using files in pascal, you can use a TextFile type, which allows you to write string into the file or create your own file type.
+
==Old procedural style==
  
<Delphi>
+
When using files in classic (non-object oriented) Pascal, you can use a file of type TextFile (or simply Text) to store text, that is typically structured in lines. Every line ends with an end-of-line marker ([[End_of_Line|LineEnding]]). You can store strings in this type of file, but also numbers which can be formatted in different ways. These files can be opened and edited inside the Lazarus IDE or any other text editor.
 +
 
 +
For specific purposes you can create your own file type that can only store one type of data. For example:
 +
 
 +
<syntaxhighlight lang=pascal>
 
...
 
...
Type
+
type
  TIFile = File Of Integer;//Allows you to write Integers into the file
+
  TIntegerFile = file of integer;  // Allows you to write only integer numbers to the file
  TCFile = File Of PChar;//Write PChars into the file :\
+
  TExtendedFile = file of extended; // Allows you to write only real numbers to the file
  TFile = File Of String;//Write Strings into the file
+
  TCharFile    = file of char;     // Allows you to write only single characters to the file
...
+
</syntaxhighlight>
</Delphi>
+
 
 +
===Input/Output error handling===
 +
 
 +
The [http://www.freepascal.org/docs-html/prog/progsu38.html#x45-440001.2.38 I/O error handling flag] tells the compiler how to deal with error situations: raise an exception or store the I/O result in the IOResult variable.
 +
The I/O error handling flag is a compiler directive. To enable or disable it:
 +
 
 +
<syntaxhighlight lang=pascal>
 +
{$I+} // Errors will lead to an EInOutError exception (default)
 +
{$I-} // Suppress I/O errors: check the IOResult variable for the error code
 +
</syntaxhighlight>
 +
 
 +
By suppressing I/O errors ({$I-}) the file operation results go into the IOResult variable. This is a [[Cardinal|cardinal (number) type]]. Different numbers mean different errors. So you may want to check the documentation for the different errors[http://www.freepascal.org/docs-html/rtl/system/ioresult.html].
 +
 
 +
===File procedures===
 +
These file handling procedures and functions are located in [[System unit|unit System]]. See the FPC documentation for more details: [http://www.freepascal.org/docs-html/rtl/system/index-5.html Reference for 'System' unit].
 +
 
 +
* '''AssignFile''' (prevent the use of the older '''[[Assign]]''' procedure) - Assign a name to a file
 +
* '''Append''' - Opens an existing file for appending data to end of file and editing it
 +
* '''BlockRead''' - Read data from an untyped file into memory
 +
* '''BlockWrite''' - Write data from memory to an untyped file
 +
* '''CloseFile''' (prevent the use of the older '''Close''' procedure) - Close opened file
 +
* '''EOF''' - Check for end of file
 +
* '''Erase''' - Erase file from disk
 +
* '''FilePos''' - Get position in file
 +
* '''FileSize''' - Get size of file
 +
* '''Flush''' - Write file buffers to disk
 +
* '''IOResult''' - Return result of last file IO operation
 +
* '''Read''' - Read from a text file
 +
* '''ReadLn''' - Read from a text file and go to the next line
 +
* '''Reset''' - Opens a file for reading
 +
* '''Rewrite''' - Create a file for writing
 +
* '''Seek''' - Change position in file
 +
* '''SeekEOF''' - Set file position to end of file
 +
* '''SeekEOLn''' - Set file position to end of line
 +
* '''Truncate''' - Truncate the file at position
 +
* '''[[Write]]''' - Write variable to a file
 +
* '''WriteLn''' - Write variable to a text file and go to a new line
 +
 
 +
===Example===
 +
A full example of handling a text file of type TextFile:
 +
 
 +
<syntaxhighlight lang=pascal>
 +
program CreateFile;
 +
 
 +
{$mode objfpc}
 +
 
 +
uses
 +
Sysutils;
 +
 
 +
const
 +
  C_FNAME = 'textfile.txt';
 +
 
 +
var
 +
  tfOut: TextFile;
 +
 
 +
begin
 +
  // Set the name of the file that will be created
 +
  AssignFile(tfOut, C_FNAME);
 +
 
 +
  // Use exceptions to catch errors (this is the default so not absolutely requried)
 +
  {$I+}
 +
 
 +
  // Embed the file creation in a try/except block to handle errors gracefully
 +
  try
 +
    // Create the file, write some text and close it.
 +
    rewrite(tfOut);
 +
 
 +
    writeln(tfOut, 'Hello textfile!');
 +
    writeln(tfOut, 'The answer to life, the universe and everything: ', 42);
 +
 
 +
    CloseFile(tfOut);
 +
 
 +
  except
 +
    // If there was an error the reason can be found here
 +
    on E: EInOutError do
 +
      writeln('File handling error occurred. Details: ', E.ClassName, '/', E.Message);
 +
  end;
 +
 
 +
  // Give feedback and wait for key press
 +
  writeln('File ', C_FNAME, ' created if all went ok. Press Enter to stop.');
 +
  readln;
 +
end.</syntaxhighlight>
 +
 
 +
Now open the file in any text editor and you will see the above text written to it!
 +
You can test the error handling by running the program once, then set the file to read-only and run the program again.
 +
 
 +
Note that exception handling was used as that is an easy way to perfom multiple file operations and handling the errors. You could also use {$I-}, but then you would have to check IOResult after each operation and modify your next operation.
 +
 
 +
Here's how appending more text to a textfile works:
 +
 
 +
<syntaxhighlight lang=pascal>
 +
program AppendToFile;
 +
 
 +
{$mode objfpc}
 +
 
 +
uses
 +
  Sysutils;
 +
 
 +
const
 +
  C_FNAME = 'textfile.txt';
 +
 
 +
var
 +
  tfOut: TextFile;
 +
 
 +
begin
 +
  // Set the name of the file that will receive some more text
 +
  AssignFile(tfOut, C_FNAME);
 +
 
 +
  // Embed the file handling in a try/except block to handle errors gracefully
 +
  try
 +
    // Open the file for appending, write some more text to it and close it.
 +
    append(tfOut);
 +
 
 +
    writeln(tfOut, 'Hello again textfile!');
 +
    writeln(tfOut, 'The result of 6 * 7 = ', 6 * 7);
 +
 
 +
    CloseFile(tfOut);
 +
 
 +
  except
 +
    on E: EInOutError do
 +
    writeln('File handling error occurred. Details: ', E.Message);
 +
  end;
 +
 
 +
  // Give feedback and wait for key press
 +
  writeln('File ', C_FNAME, ' might have more text. Press enter to stop.');
 +
  readln;
 +
end.</syntaxhighlight>
 +
 
 +
Reading a textfile:
 +
 
 +
<syntaxhighlight lang=pascal>
 +
program ReadFile;
 +
 
 +
{$mode objfpc}
 +
 
 +
uses
 +
Sysutils;
 +
 
 +
const
 +
  C_FNAME = 'textfile.txt';
 +
 
 +
var
 +
  tfIn: TextFile;
 +
  s: string;
 +
 
 +
begin
 +
  // Give some feedback
 +
  writeln('Reading the contents of file: ', C_FNAME);
 +
  writeln('=========================================');
 +
 
 +
  // Set the name of the file that will be read
 +
  AssignFile(tfIn, C_FNAME);
 +
 
 +
  // Embed the file handling in a try/except block to handle errors gracefully
 +
  try
 +
    // Open the file for reading
 +
    reset(tfIn);
 +
 
 +
    // Keep reading lines until the end of the file is reached
 +
    while not eof(tfIn) do
 +
    begin
 +
      readln(tfIn, s);
 +
      writeln(s);
 +
    end;
 +
 
 +
    // Done so close the file
 +
    CloseFile(tfIn);
 +
 
 +
  except
 +
    on E: EInOutError do
 +
    writeln('File handling error occurred. Details: ', E.Message);
 +
  end;
 +
 
 +
  // Wait for the user to end the program
 +
  writeln('=========================================');
 +
  writeln('File ', C_FNAME, ' was probably read. Press enter to stop.');
 +
  readln;
 +
end.</syntaxhighlight>
 +
 
 +
==Object style==
 +
In addition to the old style file handling routines mentioned above, a new system exists that uses the concept of streams (- of data) at a higher abstraction level. This means data can be read from or written to any location (disk, memory, hardware ports etc.) by one uniform interface.
 +
 
 +
In addition, most string handling classes have the ability to load and save content from/to a file. These methods are usually named SaveToFile and LoadFromFile. A lot of other objects (such as Lazarus grids) have similar functionality, including Lazarus datasets (DBExport). It pays to look through the documentation or source code before trying to roll your own save/load routines.
 +
 
 +
===Generic files of any type===
 +
For opening files for direct access TFileStream can be used. This class is an encapsulation of the system procedures FileOpen, FileCreate, FileRead, FileWrite, FileSeek and FileClose which resides in unit SysUtils.
 +
 
 +
[http://www.freepascal.org/docs-html/rtl/sysutils/ioroutines.html IO routines]
 +
 
 +
Here is a very simple example of appending one file to another using streams. It is equivalent to the append example above, but much simpler:
 +
 
 +
<syntaxhighlight lang=pascal>
 +
program InOutStream;
 +
 
 +
{$mode objfpc}
 +
 
 +
uses
 +
  Classes, SysUtils;
 +
var
 +
  InStream, OutStream: TFileStream;
 +
begin
 +
  if (ParamCount = 2) and
 +
    FileExists(ParamStr(1)) and
 +
    FileExists(ParamStr(2)) then
 +
  begin
 +
    InStream := TFileStream.Create(ParamStr(1), fmOpenRead);
 +
    try
 +
      OutStream := TFileStream.Create(Paramstr(2), fmOpenWrite);
 +
      try
 +
        OutStream.Position := OutStream.size;
 +
        OutStream.CopyFrom(InStream, 0); // appends
 +
      finally
 +
        OutStream.Free;
 +
      end;
 +
    finally
 +
      InStream.Free;
 +
    end;
 +
  end else
 +
    Writeln('Usage: inoutstream <infile> <outfile>');
 +
end.</syntaxhighlight><br>
 +
In the example below, note how we encapsulate the file handling action with a try..except block so that errors are handled correctly just as with the classic file handling routines (as not to convolute the example the fsOut.write is not put inside a try...finally block).
 +
 
 +
<syntaxhighlight lang=pascal>
 +
program WriteBinaryData;
  
If we only did TFile = File, then it would be impossible to write anything into it! Also, you cannot write integers directly into TFile,  because it is a file of strings. Better use the filetype TextFile for writing values of different types.
+
{$mode objfpc}
  
==IO==
+
uses
 +
  Classes, Sysutils;
  
IO is the file handling thingy for pascal. It is used for getting errors.
+
const
Since it is a compiler directive, you have to do this:
+
  C_FNAME = 'binarydata.bin';
<Delphi>
 
{$I-}//Turn off checking. This way all errors go into the IOResult variable
 
{$I+}//Turn it back on
 
</Delphi>
 
  
By disabling (Turning off) IO it all goes into the IOResult variable. This is an cardinal type(Numbers). So, if you want to write it, you have to use the InttoStr function. Different numbers mean different errors. So you may want to check here for the different errors: [http://www.efg2.com/Lab/Library/Delphi/IO/IOResult.htm]
+
var
 +
  fsOut    : TFileStream;
 +
  ChrBuffer: array[0..2] of char;
  
==File procedures==
+
begin
 +
  // Set up some random data that will get stored
 +
  ChrBuffer[0] := 'A';
 +
  ChrBuffer[1] := 'B';
 +
  ChrBuffer[2] := 'C';
  
There are three file procedures you really need to know about
+
  // Catch errors in case the file cannot be created
 +
  try
 +
    // Create the file stream instance, write to it and free it to prevent memory leaks
 +
    fsOut := TFileStream.Create( C_FNAME, fmCreate);
 +
    fsOut.Write(ChrBuffer, sizeof(ChrBuffer));
 +
    fsOut.Free;
  
'''Rewrite''' - Is used for creating files
+
  // Handle errors
 +
  except
 +
    on E:Exception do
 +
      writeln('File ', C_FNAME, ' could not be created because: ', E.Message);
 +
  end;
  
'''Append''' - Opens an existing file for editing it
+
  // Give feedback and wait for key press
 +
  writeln('File ', C_FNAME, ' created if all went ok. Press Enter to stop.');
 +
  readln;
 +
end.</syntaxhighlight>
  
'''Reset''' - Opens a file for reading it
 
  
==Example==
+
You can load entire files into memory too if its size is comparatively smaller than available system memory. Bigger sizes might work but your operating system will start using the page/swap file, making the exercise useless from a performance standpoint.
  
A full example of handling a text file of type TextFile:
+
<syntaxhighlight lang=pascal>
 +
program ReadBinaryDataInMemoryForAppend;
 +
 
 +
{$mode objfpc}
  
<Delphi>
+
uses
Program FileTest;
+
  Classes, Sysutils;
  
{$mode objfpc} //Do not forget this ever
+
const
 +
  C_FNAME = 'binarydata.bin';
  
Var
+
var
FileVar:TextFile;
+
  msApp: TMemoryStream;
  
 
begin
 
begin
   Writeln('File Test');
+
   // Set up the stream
  AssignFile(FileVar,'Test.txt'); // you do not have to put .txt but this is just for now
+
  msApp := TMemoryStream.Create;
  {$I-}
+
 
  Try
+
  // Catch errors in case the file cannot be read or written
  Rewrite(FileVar); // creating the file
+
  try
  Writeln(FileVar,'Hello');
+
    // Read the data into memory
   Except
+
    msApp.LoadFromFile(C_FNAME);
   Writeln('ERROR! IORESULT: '+InttoStr(IOResult);
+
 
   End;
+
    // Seek the end of the stream so data can be appended
   CloseFile(FileVar);
+
    msApp.Seek(0, soEnd);
   Readln;
+
 
 +
    // Write some arbitrary data to the memory stream
 +
    msApp.WriteByte(68);
 +
    msApp.WriteAnsiString('Some extra text');
 +
    msApp.WriteDWord(671202);
 +
 
 +
    // Store the data back on disk, overwriting the previous contents
 +
    msApp.SaveToFile(C_FNAME);
 +
 
 +
   // Handle errors
 +
   except
 +
    on E:Exception do
 +
      writeln('File ', C_FNAME, ' could not be read or written because: ', E.Message);
 +
   end;
 +
 
 +
  // Clean up
 +
  msApp.Free;
 +
 
 +
   // Give feedback and wait for key press
 +
  writeln('File ', C_FNAME, ' was extended if all went ok. Press Enter to stop.');
 +
   readln;
 
end.
 
end.
</Delphi>
+
</syntaxhighlight>
 +
 
 +
With larger files of many Gb, you may want to read in buffers of, say, 4096 bytes (you're advised to use a multiple of the filesytem cluster or block size) and do something with the data of each buffer read.
 +
 
 +
<syntaxhighlight lang=pascal>
 +
var
 +
  TotalBytesRead, BytesRead : Int64;
 +
  Buffer : array [0..4095] of byte;  // or, array [0..4095] of char
 +
  FileStream : TFileStream;
 +
 
 +
try
 +
  FileStream := TFileStream.Create;
 +
  FileStream.Position := 0;  // Ensure you are at the start of the file
 +
  TotalBytesRead := 0;
 +
  while TotalBytesRead <= FileStream.Size do  // While the amount of data read is less than or equal to the size of the stream do
 +
  begin
 +
    BytesRead := FileStream.Read(Buffer, SizeOf(Buffer));  // Read in 4096 of data
 +
    Inc(TotalBytesRead, BytesRead);                      // Increase TotalByteRead by the size of the buffer, i.e. 4096 bytes
 +
    // Do something with Buffer data
 +
  end;   
 +
</syntaxhighlight>
 +
 
 +
=== FileCopy ===
 +
With the above, we can implement a simple FileCopy function (FreePascal has none in its RTL although Lazarus has [[CopyFile]]) - adjust as needed for bigger files etc:
  
Now open the file in any text editor and you will see Hello written to it!
+
<syntaxhighlight lang=pascal>
 +
program FileCopyDemo;
 +
// Demonstration of FileCopy function
  
Heres appending to a file(Editing it)
+
{$mode objfpc}
  
<Delphi>
+
uses
Program EditFile;
+
  Classes;
  
Var
+
const
File1:TextFile;
+
  fSource = 'test.txt';
+
  fTarget = 'test.bak';
 +
 
 +
function FileCopy(Source, Target: string): boolean;
 +
// Copies source to target; overwrites target.
 +
// Caches entire file content in memory.
 +
// Returns true if succeeded; false if failed.
 +
var
 +
  MemBuffer: TMemoryStream;
 
begin
 
begin
   Writeln('Append file');
+
   Result := false;
  AssignFile(File1,'File.txt');
+
  MemBuffer := TMemoryStream.Create;
   {$I-}
+
  try
   Try
+
    MemBuffer.LoadFromFile(Source);
   Append(File1,'Some Text');
+
    MemBuffer.SaveToFile(Target);  
  Except
+
    Result := true
  Writeln('ERROR IORESULT:'+IntToStr(IOResult));
+
   except
   End;
+
    //swallow exception; function result is false by default
  {$I+}
+
   end;
  CloseFile(File1);
+
   // Clean up
  Readln;
+
  MemBuffer.Free
 +
end;
 +
 
 +
begin
 +
  If FileCopy(fSource, fTarget)
 +
    then Writeln('File ', fSource, ' copied to ', fTarget)
 +
    else Writeln('File ', fSource, ' not copied to ', fTarget);
 +
   Readln()
 
end.
 
end.
</Delphi>
+
</syntaxhighlight>
 +
 
 +
===Handling Text files (TStringList)===
 +
In general, for text files you can use the TStringList class to load the entire file into memory and have easy access to its lines. Of course, you can also write the StringList back to a file:
 +
 
 +
<syntaxhighlight lang=pascal>
 +
program StringListDemo;
 +
 
 +
{$mode objfpc}
 +
 
 +
uses
 +
  Classes, SysUtils;
  
Reading a file:
+
const
 +
  C_FNAME = 'textfile.txt';
  
<Delphi>
+
var
Program ReadFile;
+
  slInfo: TStringList;
  
Var
 
File1:TextFile;
 
Str:String;
 
 
 
begin
 
begin
   Writeln('File Reading:');
+
   // Create an instance of the string list to handle the textfile
  AssignFile(File1,'File,txt');
+
  slInfo := TStringList.Create;
  {$I-}
+
 
  Try
+
  // Embed the file handling in a try/except block to handle errors gracefully
  Reset(File1);
+
  try
  Repeat
+
    // Load the contents of the textfile completely in memory
  Readln(File1,Str);//Reads the whole line from the file
+
    slInfo.LoadFromFile(C_FNAME);
  Writeln(Str);//Writes the line read
+
 
  Until(EOF(File1));EOF(End Of File) The the program will keep reading new lines until there is none.
+
    // Add some more contents
  Except
+
    slInfo.Add('An extra line appended to the text');
  Writeln('ERROR IORESULT:'+IntToStr(IOResult));
+
    slInfo.Add('And another one.');
 +
    slInfo.Add('Let''s stop here.');
 +
    slInfo.Add('It is now ' + DateTimeToStr(now));
 +
 
 +
    // And write the contents back to disk, replacing the original contents
 +
    slInfo.SaveToFile(C_FNAME);
 +
 
 +
  except
 +
    // If there was an error the reason can be found here
 +
    on E: EInOutError do
 +
      writeln('File handling error occurred. Reason: ', E.Message);
 
   end;
 
   end;
   {$I+}
+
 
   CloseFile(File1);
+
  // Clean up
   Readln;
+
  slInfo.Free;
 +
 
 +
  // Give feedback and wait for key press
 +
  writeln('File ', C_FNAME, ' updated if all went ok. Press Enter to stop.');
 +
   readln;
 +
end.</syntaxhighlight>
 +
 
 +
===Demo: save single string to a file===
 +
In order to write a single string to a stream you might want to use the procedure defined below. Note that strings in FreePascal can be extremely long, this is also a useful way to write a big block of textdata to a file.
 +
 
 +
<syntaxhighlight lang=pascal>program SaveStringToPathDemo;
 +
 
 +
{$mode objfpc}
 +
 
 +
uses
 +
   Classes, sysutils;
 +
 
 +
const
 +
  C_FNAME = 'textstringtofile.txt';
 +
 
 +
// SaveStringToFile: function to store a string of text into a diskfile.
 +
//  If the function result equals true, the string was written ok.
 +
//  If not then there was some kind of error.
 +
function SaveStringToFile(theString, filePath: AnsiString): boolean;
 +
var
 +
   fsOut: TFileStream;
 +
begin
 +
  // By default assume the writing will fail.
 +
  result := false;
 +
 
 +
  // Write the given string to a file, catching potential errors in the process.
 +
  try
 +
    fsOut := TFileStream.Create(filePath, fmCreate);
 +
    fsOut.Write(theString[1], length(theString));
 +
    fsOut.Free;
 +
 
 +
    // At his point it is known that the writing went ok.
 +
    result := true
 +
 
 +
  except
 +
    on E:Exception do
 +
      writeln('String could not be written. Details: ', E.ClassName, ': ', E.Message);
 +
  end
 +
end;
 +
 
 +
//
 +
// Main program
 +
//
 +
begin
 +
  // Try to save a simple textstring in a file and give feedback of sucess.
 +
  if SaveStringToFile('>> this text gets stored <<', C_FNAME) then
 +
    writeln('Text succesfully written to a file')
 +
  else
 +
    writeln('Writing text to a file failed.');
 +
 
 +
  // Wait for the user to press Enter
 +
  readln
 
end.
 
end.
</Delphi>
+
</syntaxhighlight>
  
==Other file procedures==
+
==File Handling in ISO Mode==
  
The SysUtils and some other units have procedures for making text files. [http://www.freepascal.org/docs-html/rtl/sysutils/ioroutines.html]
+
===Command Line Parameters===
  
==OOP==
+
The first option to assign external to internal files in iso mode is through command line parameters according to their order of appearance. Example:
  
Creating TextFiles in OOP (Object Orientated Pascal) is simple and fast. Mainly because most objects have a SaveToFile procedure.
+
<syntaxhighlight lang=pascal>
 +
program isotest1 (file1, file2);
 +
var
 +
  file1: text;
 +
  file2: file of integer;
 +
begin
 +
  reset(file1);
 +
  readln(file1);
 +
  rewrite(file2);
 +
  write(file2, 5);
 +
end.
 +
</syntaxhighlight>
 +
 
 +
The program is compiled with <code>fpc -Miso isotest1.pas</code> and run with <code>./isotest1 external1.txt external2.dat </code>.  files1 is assigned to external1.txt and file2 to external2.dat. Without command line parameters the files are assigned to stdin and stdout. As long as there is only one file for input and one for output, the same assignment can be achieved with this command: <code>./isotest1 <external1.txt >external2.dat </code>. file1 must exist prior to the run, file2 will be created.
  
The usage is similar to that of a TStringList:
+
===Transparent File Names===
  
<Delphi>
+
The second option is transparent file names, achieved with the compiler option -Sr. Example:
Var
 
Str:TStringList;
 
  
 +
<syntaxhighlight lang=pascal>
 +
program isotest2 (file1, file2);
 +
var
 +
  file1: text;
 +
  file2: text;
 
begin
 
begin
   Str := TStringList.Create;
+
   reset(file1);
   Str.Add('Hello');
+
  readln(file1);
   Str.SaveToFile(<File Path Here>);
+
   rewrite(file2);
end;
+
   write(file2, 5);
</Delphi>
+
end.
 +
</syntaxhighlight>
 +
 
 +
If the program is compiled with <code>fpc -Miso -Sr isotest2.pas</code> and run without command line parameters, the external files FILE1.txt and FILE2.txt are read and written. Note the uppercase conversion of the internal filenames. Files with different filenames can still be used through command line parameters.
 +
 
 +
==See also==
  
I hope this is helpful :D
+
* [[CopyFile]] Lazarus function (also available for command line programs) that copies files for you
And if anything is wrong or I left something out. '''Edit At Will!'''
+
* [[File]]
 +
* [[Howto Use TOpenDialog]]
 +
* [[Howto Use TSaveDialog]]

Latest revision as of 05:53, 12 October 2023

العربية (ar) English (en) español (es) suomi (fi) français (fr) 日本語 (ja) русский (ru) 中文(中国大陆)‎ (zh_CN) 中文(台灣)‎ (zh_TW)

Overview

Something every programmer needs to know is how to work with files. Files are used to persist data i.e. store data in such a way that it can be retrieved at a later time, without having to recreate it. Files can be used to store user settings, error logs, measurement or calculation results, and more. This page explains the basics of file handling.

Old procedural style

When using files in classic (non-object oriented) Pascal, you can use a file of type TextFile (or simply Text) to store text, that is typically structured in lines. Every line ends with an end-of-line marker (LineEnding). You can store strings in this type of file, but also numbers which can be formatted in different ways. These files can be opened and edited inside the Lazarus IDE or any other text editor.

For specific purposes you can create your own file type that can only store one type of data. For example:

...
type
  TIntegerFile  = file of integer;  // Allows you to write only integer numbers to the file
  TExtendedFile = file of extended; // Allows you to write only real numbers to the file
  TCharFile     = file of char;     // Allows you to write only single characters to the file

Input/Output error handling

The I/O error handling flag tells the compiler how to deal with error situations: raise an exception or store the I/O result in the IOResult variable. The I/O error handling flag is a compiler directive. To enable or disable it:

{$I+} // Errors will lead to an EInOutError exception (default)
{$I-} // Suppress I/O errors: check the IOResult variable for the error code

By suppressing I/O errors ({$I-}) the file operation results go into the IOResult variable. This is a cardinal (number) type. Different numbers mean different errors. So you may want to check the documentation for the different errors[1].

File procedures

These file handling procedures and functions are located in unit System. See the FPC documentation for more details: Reference for 'System' unit.

  • AssignFile (prevent the use of the older Assign procedure) - Assign a name to a file
  • Append - Opens an existing file for appending data to end of file and editing it
  • BlockRead - Read data from an untyped file into memory
  • BlockWrite - Write data from memory to an untyped file
  • CloseFile (prevent the use of the older Close procedure) - Close opened file
  • EOF - Check for end of file
  • Erase - Erase file from disk
  • FilePos - Get position in file
  • FileSize - Get size of file
  • Flush - Write file buffers to disk
  • IOResult - Return result of last file IO operation
  • Read - Read from a text file
  • ReadLn - Read from a text file and go to the next line
  • Reset - Opens a file for reading
  • Rewrite - Create a file for writing
  • Seek - Change position in file
  • SeekEOF - Set file position to end of file
  • SeekEOLn - Set file position to end of line
  • Truncate - Truncate the file at position
  • Write - Write variable to a file
  • WriteLn - Write variable to a text file and go to a new line

Example

A full example of handling a text file of type TextFile:

program CreateFile;

{$mode objfpc}

uses
 Sysutils;

const
  C_FNAME = 'textfile.txt';

var
  tfOut: TextFile;

begin
  // Set the name of the file that will be created
  AssignFile(tfOut, C_FNAME);

  // Use exceptions to catch errors (this is the default so not absolutely requried)
  {$I+}

  // Embed the file creation in a try/except block to handle errors gracefully
  try
    // Create the file, write some text and close it.
    rewrite(tfOut);

    writeln(tfOut, 'Hello textfile!');
    writeln(tfOut, 'The answer to life, the universe and everything: ', 42);

    CloseFile(tfOut);

  except
    // If there was an error the reason can be found here
    on E: EInOutError do
      writeln('File handling error occurred. Details: ', E.ClassName, '/', E.Message);
  end;

  // Give feedback and wait for key press
  writeln('File ', C_FNAME, ' created if all went ok. Press Enter to stop.');
  readln;
end.

Now open the file in any text editor and you will see the above text written to it! You can test the error handling by running the program once, then set the file to read-only and run the program again.

Note that exception handling was used as that is an easy way to perfom multiple file operations and handling the errors. You could also use {$I-}, but then you would have to check IOResult after each operation and modify your next operation.

Here's how appending more text to a textfile works:

program AppendToFile;

{$mode objfpc}

uses
 Sysutils;

const
  C_FNAME = 'textfile.txt';

var
  tfOut: TextFile;

begin
  // Set the name of the file that will receive some more text
  AssignFile(tfOut, C_FNAME);

  // Embed the file handling in a try/except block to handle errors gracefully
  try
    // Open the file for appending, write some more text to it and close it.
    append(tfOut);

    writeln(tfOut, 'Hello again textfile!');
    writeln(tfOut, 'The result of 6 * 7 = ', 6 * 7);

    CloseFile(tfOut);

  except
    on E: EInOutError do
     writeln('File handling error occurred. Details: ', E.Message);
  end;

  // Give feedback and wait for key press
  writeln('File ', C_FNAME, ' might have more text. Press enter to stop.');
  readln;
end.

Reading a textfile:

program ReadFile;

{$mode objfpc}

uses
 Sysutils;

const
  C_FNAME = 'textfile.txt';

var
  tfIn: TextFile;
  s: string;

begin
  // Give some feedback
  writeln('Reading the contents of file: ', C_FNAME);
  writeln('=========================================');

  // Set the name of the file that will be read
  AssignFile(tfIn, C_FNAME);

  // Embed the file handling in a try/except block to handle errors gracefully
  try
    // Open the file for reading
    reset(tfIn);

    // Keep reading lines until the end of the file is reached
    while not eof(tfIn) do
    begin
      readln(tfIn, s);
      writeln(s);
    end;

    // Done so close the file
    CloseFile(tfIn);

  except
    on E: EInOutError do
     writeln('File handling error occurred. Details: ', E.Message);
  end;

  // Wait for the user to end the program
  writeln('=========================================');
  writeln('File ', C_FNAME, ' was probably read. Press enter to stop.');
  readln;
end.

Object style

In addition to the old style file handling routines mentioned above, a new system exists that uses the concept of streams (- of data) at a higher abstraction level. This means data can be read from or written to any location (disk, memory, hardware ports etc.) by one uniform interface.

In addition, most string handling classes have the ability to load and save content from/to a file. These methods are usually named SaveToFile and LoadFromFile. A lot of other objects (such as Lazarus grids) have similar functionality, including Lazarus datasets (DBExport). It pays to look through the documentation or source code before trying to roll your own save/load routines.

Generic files of any type

For opening files for direct access TFileStream can be used. This class is an encapsulation of the system procedures FileOpen, FileCreate, FileRead, FileWrite, FileSeek and FileClose which resides in unit SysUtils.

IO routines

Here is a very simple example of appending one file to another using streams. It is equivalent to the append example above, but much simpler:

program InOutStream;

{$mode objfpc}

uses
  Classes, SysUtils;
var
  InStream, OutStream: TFileStream;
begin
  if (ParamCount = 2) and
    FileExists(ParamStr(1)) and
    FileExists(ParamStr(2)) then
  begin
    InStream := TFileStream.Create(ParamStr(1), fmOpenRead);
    try
      OutStream := TFileStream.Create(Paramstr(2), fmOpenWrite);
      try
        OutStream.Position := OutStream.size;
        OutStream.CopyFrom(InStream, 0); // appends
      finally
        OutStream.Free;
      end;
    finally
      InStream.Free;
    end;
  end else 
    Writeln('Usage: inoutstream <infile> <outfile>');
end.


In the example below, note how we encapsulate the file handling action with a try..except block so that errors are handled correctly just as with the classic file handling routines (as not to convolute the example the fsOut.write is not put inside a try...finally block).

program WriteBinaryData;

{$mode objfpc}

uses
  Classes, Sysutils;

const
  C_FNAME = 'binarydata.bin';

var
  fsOut    : TFileStream;
  ChrBuffer: array[0..2] of char;

begin
  // Set up some random data that will get stored
  ChrBuffer[0] := 'A';
  ChrBuffer[1] := 'B';
  ChrBuffer[2] := 'C';

  // Catch errors in case the file cannot be created
  try
    // Create the file stream instance, write to it and free it to prevent memory leaks
    fsOut := TFileStream.Create( C_FNAME, fmCreate);
    fsOut.Write(ChrBuffer, sizeof(ChrBuffer));
    fsOut.Free;

  // Handle errors
  except
    on E:Exception do
      writeln('File ', C_FNAME, ' could not be created because: ', E.Message);
  end;

  // Give feedback and wait for key press
  writeln('File ', C_FNAME, ' created if all went ok. Press Enter to stop.');
  readln;
end.


You can load entire files into memory too if its size is comparatively smaller than available system memory. Bigger sizes might work but your operating system will start using the page/swap file, making the exercise useless from a performance standpoint.

program ReadBinaryDataInMemoryForAppend;

{$mode objfpc}

uses
  Classes, Sysutils;

const
  C_FNAME = 'binarydata.bin';

var
  msApp: TMemoryStream;

begin
  // Set up the stream
  msApp := TMemoryStream.Create;

  // Catch errors in case the file cannot be read or written
  try
    // Read the data into memory
    msApp.LoadFromFile(C_FNAME);

    // Seek the end of the stream so data can be appended
    msApp.Seek(0, soEnd);

    // Write some arbitrary data to the memory stream
    msApp.WriteByte(68);
    msApp.WriteAnsiString('Some extra text');
    msApp.WriteDWord(671202);

    // Store the data back on disk, overwriting the previous contents
    msApp.SaveToFile(C_FNAME);

  // Handle errors
  except
    on E:Exception do
      writeln('File ', C_FNAME, ' could not be read or written because: ', E.Message);
  end;

  // Clean up
  msApp.Free;

  // Give feedback and wait for key press
  writeln('File ', C_FNAME, ' was extended if all went ok. Press Enter to stop.');
  readln;
end.

With larger files of many Gb, you may want to read in buffers of, say, 4096 bytes (you're advised to use a multiple of the filesytem cluster or block size) and do something with the data of each buffer read.

var
  TotalBytesRead, BytesRead : Int64;
  Buffer : array [0..4095] of byte;  // or, array [0..4095] of char
  FileStream : TFileStream;

try
  FileStream := TFileStream.Create;
  FileStream.Position := 0;  // Ensure you are at the start of the file
  TotalBytesRead := 0;
  while TotalBytesRead <= FileStream.Size do  // While the amount of data read is less than or equal to the size of the stream do
  begin
    BytesRead := FileStream.Read(Buffer, SizeOf(Buffer));  // Read in 4096 of data
    Inc(TotalBytesRead, BytesRead);                       // Increase TotalByteRead by the size of the buffer, i.e. 4096 bytes
    // Do something with Buffer data
  end;

FileCopy

With the above, we can implement a simple FileCopy function (FreePascal has none in its RTL although Lazarus has CopyFile) - adjust as needed for bigger files etc:

program FileCopyDemo;
// Demonstration of FileCopy function

{$mode objfpc}

uses
  Classes;

const
  fSource = 'test.txt';
  fTarget = 'test.bak';

function FileCopy(Source, Target: string): boolean;
// Copies source to target; overwrites target.
// Caches entire file content in memory.
// Returns true if succeeded; false if failed.
var
  MemBuffer: TMemoryStream;
begin
  Result := false;
  MemBuffer := TMemoryStream.Create;
  try
    MemBuffer.LoadFromFile(Source);
    MemBuffer.SaveToFile(Target); 
    Result := true
  except
    //swallow exception; function result is false by default
  end;
  // Clean up
  MemBuffer.Free
end;

begin
  If FileCopy(fSource, fTarget)
    then Writeln('File ', fSource, ' copied to ', fTarget)
    else Writeln('File ', fSource, ' not copied to ', fTarget);
  Readln()
end.

Handling Text files (TStringList)

In general, for text files you can use the TStringList class to load the entire file into memory and have easy access to its lines. Of course, you can also write the StringList back to a file:

program StringListDemo;

{$mode objfpc}

uses
  Classes, SysUtils;

const
  C_FNAME = 'textfile.txt';

var
  slInfo: TStringList;

begin
  // Create an instance of the string list to handle the textfile
  slInfo := TStringList.Create;

  // Embed the file handling in a try/except block to handle errors gracefully
  try
    // Load the contents of the textfile completely in memory
    slInfo.LoadFromFile(C_FNAME);

    // Add some more contents
    slInfo.Add('An extra line appended to the text');
    slInfo.Add('And another one.');
    slInfo.Add('Let''s stop here.');
    slInfo.Add('It is now ' + DateTimeToStr(now));

    // And write the contents back to disk, replacing the original contents
    slInfo.SaveToFile(C_FNAME);

  except
    // If there was an error the reason can be found here
    on E: EInOutError do
      writeln('File handling error occurred. Reason: ', E.Message);
  end;

  // Clean up
  slInfo.Free;

  // Give feedback and wait for key press
  writeln('File ', C_FNAME, ' updated if all went ok. Press Enter to stop.');
  readln;
end.

Demo: save single string to a file

In order to write a single string to a stream you might want to use the procedure defined below. Note that strings in FreePascal can be extremely long, this is also a useful way to write a big block of textdata to a file.

program SaveStringToPathDemo;

{$mode objfpc}

uses
  Classes, sysutils;

const
  C_FNAME = 'textstringtofile.txt';

// SaveStringToFile: function to store a string of text into a diskfile.
//   If the function result equals true, the string was written ok.
//   If not then there was some kind of error.
function SaveStringToFile(theString, filePath: AnsiString): boolean;
var
  fsOut: TFileStream;
begin
  // By default assume the writing will fail.
  result := false;

  // Write the given string to a file, catching potential errors in the process.
  try
    fsOut := TFileStream.Create(filePath, fmCreate);
    fsOut.Write(theString[1], length(theString));
    fsOut.Free;

    // At his point it is known that the writing went ok.
    result := true

  except
    on E:Exception do
      writeln('String could not be written. Details: ', E.ClassName, ': ', E.Message);
  end
end;

//
// Main program
//
begin
  // Try to save a simple textstring in a file and give feedback of sucess.
  if SaveStringToFile('>> this text gets stored <<', C_FNAME) then
    writeln('Text succesfully written to a file')
  else
    writeln('Writing text to a file failed.');

  // Wait for the user to press Enter
  readln
end.

File Handling in ISO Mode

Command Line Parameters

The first option to assign external to internal files in iso mode is through command line parameters according to their order of appearance. Example:

program isotest1 (file1, file2);
var
  file1: text;
  file2: file of integer;
begin
  reset(file1);
  readln(file1);
  rewrite(file2);
  write(file2, 5);
end.

The program is compiled with fpc -Miso isotest1.pas and run with ./isotest1 external1.txt external2.dat . files1 is assigned to external1.txt and file2 to external2.dat. Without command line parameters the files are assigned to stdin and stdout. As long as there is only one file for input and one for output, the same assignment can be achieved with this command: ./isotest1 <external1.txt >external2.dat . file1 must exist prior to the run, file2 will be created.

Transparent File Names

The second option is transparent file names, achieved with the compiler option -Sr. Example:

program isotest2 (file1, file2);
var
  file1: text;
  file2: text;
begin
  reset(file1);
  readln(file1);
  rewrite(file2);
  write(file2, 5);
end.

If the program is compiled with fpc -Miso -Sr isotest2.pas and run without command line parameters, the external files FILE1.txt and FILE2.txt are read and written. Note the uppercase conversion of the internal filenames. Files with different filenames can still be used through command line parameters.

See also