Torque 3D - Script Manual: FileObject Class Reference

TorqueScript

Main   Class List   Namespace List   Online

FileObject Class Reference
[File I/O]

This class is responsible opening, reading, creating, and saving file contents. More...

Inheritance diagram for FileObject:

List of all members.

Public Member Functions

void close ()
 Close the file.
bool isEOF ()
 Determines if the parser for this FileObject has reached the end of the file.
bool openForAppend (string filename)
 Open a specified file for writing, adding data to the end of the file.
bool openForRead (string filename)
 Open a specified file for reading.
bool openForWrite (string filename)
 Open a specified file for writing.
string peekLine ()
 Read a line from the file without moving the stream position.
string readLine ()
 Read a line from file.
void writeLine (string text)
 Write a line to the file, if it was opened for writing.
void writeObject (SimObject *object)
 Write an object to a text file.
void writeObject (SimObject *object, string prepend)
 Write an object to a text file, with some data added first.

Detailed Description

This class is responsible opening, reading, creating, and saving file contents.

FileObject acts as the interface with OS level files. You create a new FileObject and pass into it a file's path and name. The FileObject class supports three distinct operations for working with files:

OperationFileObject MethodDescription
ReadopenForRead()Open the file for reading
WriteopenForWrite()Open the file for writing to and replace its contents (if any)
AppendopenForAppend()Open the file and start writing at its end

Before you may work with a file you need to use one of the three above methods on the FileObject.

Example:
// Create a file object for writing
%fileWrite = new FileObject();

// Open a file to write to, if it does not exist it will be created
%result = %fileWrite.OpenForWrite("./test.txt");

if ( %result )
{
   // Write a line to the text files
   %fileWrite.writeLine("READ. READ CODE. CODE");
}

// Close the file when finished
%fileWrite.close();

// Cleanup the file object
%fileWrite.delete();


// Create a file object for reading
%fileRead = new FileObject();

// Open a text file, if it exists
%result = %fileRead.OpenForRead("./test.txt");

if ( %result )
{
   // Read in the first line
   %line = %fileRead.readline();

   // Print the line we just read
   echo(%line);
}

// Close the file when finished
%fileRead.close();

// Cleanup the file object
%fileRead.delete();

Member Function Documentation

void FileObject::close (  ) 

Close the file.

It is EXTREMELY important that you call this function when you are finished reading or writing to a file. Failing to do so is not only a bad programming practice, but could result in bad data or corrupt files. Remember: Open, Read/Write, Close, Delete...in that order!

Example:
// Create a file object for reading
%fileRead = new FileObject();

// Open a text file, if it exists
%fileRead.OpenForRead("./test.txt");

// Peek the first line
%line = %fileRead.peekLine();

// Print the line we just peeked
echo(%line);
// If we peek again...
%line = %fileRead.peekLine();

// We will get the same output as the first time
// since the stream did not move forward
echo(%line);

// Close the file when finished
%fileWrite.close();

// Cleanup the file object
%fileWrite.delete();
bool FileObject::isEOF (  ) 

Determines if the parser for this FileObject has reached the end of the file.

Example:
// Create a file object for reading
%fileRead = new FileObject();

// Open a text file, if it exists
%fileRead.OpenForRead("./test.txt");

// Keep reading until we reach the end of the file
while( !%fileRead.isEOF() )
{
   %line = %fileRead.readline();
   echo(%line);
}

// Made it to the end
echo("Finished reading file");
Returns:
True if the parser has reached the end of the file, false otherwise
bool FileObject::openForAppend ( string  filename  ) 

Open a specified file for writing, adding data to the end of the file.

There is no limit as to what kind of file you can write. Any format and data is allowable, not just text. Unlike openForWrite(), which will erase an existing file if it is opened, openForAppend() preserves data in an existing file and adds to it.

Parameters:
filename Path, name, and extension of file to append to
Example:
// Create a file object for writing
%fileWrite = new FileObject();

// Open a file to write to, if it does not exist it will be created
// If it does exist, whatever we write will be added to the end
%result = %fileWrite.OpenForAppend("./test.txt");
Returns:
True if file was successfully opened, false otherwise
bool FileObject::openForRead ( string  filename  ) 

Open a specified file for reading.

There is no limit as to what kind of file you can read. Any format and data contained within is accessible, not just text

Parameters:
filename Path, name, and extension of file to be read
Example:
// Create a file object for reading
%fileRead = new FileObject();

// Open a text file, if it exists
%result = %fileRead.OpenForRead("./test.txt");
Returns:
True if file was successfully opened, false otherwise
bool FileObject::openForWrite ( string  filename  ) 

Open a specified file for writing.

There is no limit as to what kind of file you can write. Any format and data is allowable, not just text

Parameters:
filename Path, name, and extension of file to write to
Example:
// Create a file object for writing
%fileWrite = new FileObject();

// Open a file to write to, if it does not exist it will be created
%result = %fileWrite.OpenForWrite("./test.txt");
Returns:
True if file was successfully opened, false otherwise
string FileObject::peekLine (  ) 

Read a line from the file without moving the stream position.

Emphasis on *line*, as in you cannot parse individual characters or chunks of data. There is no limitation as to what kind of data you can read. Unlike readLine, the parser does not move forward after reading.

Parameters:
filename Path, name, and extension of file to be read
Example:
// Create a file object for reading
%fileRead = new FileObject();

// Open a text file, if it exists
%fileRead.OpenForRead("./test.txt");

// Peek the first line
%line = %fileRead.peekLine();

// Print the line we just peeked
echo(%line);
// If we peek again...
%line = %fileRead.peekLine();

// We will get the same output as the first time
// since the stream did not move forward
echo(%line);
Returns:
String containing the line of data that was just peeked
string FileObject::readLine (  ) 

Read a line from file.

Emphasis on *line*, as in you cannot parse individual characters or chunks of data. There is no limitation as to what kind of data you can read.

Example:
// Create a file object for reading
%fileRead = new FileObject();

// Open a text file, if it exists
%fileRead.OpenForRead("./test.txt");

// Read in the first line
%line = %fileRead.readline();

// Print the line we just read
echo(%line);
Returns:
String containing the line of data that was just read
void FileObject::writeLine ( string  text  ) 

Write a line to the file, if it was opened for writing.

There is no limit as to what kind of text you can write. Any format and data is allowable, not just text. Be careful of what you write, as whitespace, current values, and literals will be preserved.

Parameters:
text The data we are writing out to file.
Example:
// Create a file object for writing
%fileWrite = new FileObject();

// Open a file to write to, if it does not exist it will be created
%fileWrite.OpenForWrite("./test.txt");

// Write a line to the text files
%fileWrite.writeLine("READ. READ CODE. CODE");
Returns:
True if file was successfully opened, false otherwise
void FileObject::writeObject ( SimObject object  ) 

Write an object to a text file.

Unlike a simple writeLine using specified strings, this function writes an entire object to file, preserving its type, name, and properties. This is similar to the save() functionality of the SimObject class, but with a bit more control.

Parameters:
object The SimObject being written to file, properties, name, and all.
Example:
// Let's assume this SpawnSphere was created and currently
// exists in the running level
new SpawnSphere(TestSphere)
{
   spawnClass = "Player";
   spawnDatablock = "DefaultPlayerData";
   autoSpawn = "1";
   radius = "5";
   sphereWeight = "1";
   indoorWeight = "1";
   outdoorWeight = "1";
   dataBlock = "SpawnSphereMarker";
   position = "-42.222 1.4845 4.80334";
   rotation = "0 0 -1 108";
   scale = "1 1 1";
   canSaveDynamicFields = "1";
};

// Create a file object for writing
%fileWrite = new FileObject();

// Open a file to write to, if it does not exist it will be created
%fileWrite.OpenForWrite("./spawnSphers.txt");

// Write out the TestSphere
%fileWrite.writeObject(TestSphere);

// Close the text file
%fileWrite.close();

// Cleanup
%fileWrite.delete();
void FileObject::writeObject ( SimObject object,
string  prepend 
)

Write an object to a text file, with some data added first.

Unlike a simple writeLine using specified strings, this function writes an entire object to file, preserving its type, name, and properties. This is similar to the save() functionality of the SimObject class, but with a bit more control.

Parameters:
object The SimObject being written to file, properties, name, and all.
prepend Data or text that is written out before the SimObject.
Example:
// Let's assume this SpawnSphere was created and currently
// exists in the running level
new SpawnSphere(TestSphere)
{
   spawnClass = "Player";
   spawnDatablock = "DefaultPlayerData";
   autoSpawn = "1";
   radius = "5";
   sphereWeight = "1";
   indoorWeight = "1";
   outdoorWeight = "1";
   dataBlock = "SpawnSphereMarker";
   position = "-42.222 1.4845 4.80334";
   rotation = "0 0 -1 108";
   scale = "1 1 1";
   canSaveDynamicFields = "1";
};

// Create a file object for writing
%fileWrite = new FileObject();

// Open a file to write to, if it does not exist it will be created
%fileWrite.OpenForWrite("./spawnSphers.txt");

// Write out the TestSphere, with a prefix
%fileWrite.writeObject(TestSphere, "$mySphere = ");

// Close the text file
%fileWrite.close();

// Cleanup
%fileWrite.delete();


Copyright © GarageGames, LLC. All Rights Reserved.