Libraries.System.FileWriter Documentation

This class represents a sequential file writer. It is the standard file writer used in Quorum. By "sequential," we mean that it is possible to only move forward in the file. Once data has been written to a position, it is impossible to go backwards in the file and modify it. This is most commonly used for writing plain text files.

Example Code

use Libraries.System.File
use Libraries.System.FileWriter

// Write three lines to an existing file.
File f
f:SetPath("anExistingFile.txt")
FileWriter writer
writer:OpenForWriteAppend(f)

// Write 3 lines.
writer:WriteLine("1")
writer:WriteLine("2")
writer:WriteLine("3")

// Close.
writer:Close()

// Open a new file and write "abcdefgh" to it.

f:SetPath("MySpecialDocument.dat")
writer:OpenForWrite(f)

// Write "abcdefgh" to the file in two separate writes.
writer:Write("abcd")
writer:Write("efgh")

// Always call Close().
writer:Close()

// The file contents are now "abcdefgh".

Inherits from: Libraries.System.Blueprints.FileWriterBlueprint, Libraries.Language.Object

Summary

Actions Summary Table

ActionsDescription
Close()When we open a file for writing, the operating system marks the file as unavailable for other applications.
Compare(Libraries.Language.Object object)This action compares two object hash codes and returns a CompareResult.
Equals(Libraries.Language.Object object)This action determines if two objects are equal based on their hash code values.
GetHashCode()This action gets the hash code for an object.
OpenForWrite(Libraries.System.File file)Open a file for sequential writing.
OpenForWriteAppend(Libraries.System.File file)Open a file for sequential writing, but preserve previous file contents.
PushToDisk()When using FileWriter, the contents written to the file are not necessarily written directly to the hard drive immediately.
Write(text textToWrite)Writes the given text to the file.
WriteLine(text textToWrite)Writes the given text to the file, but also appends a newline character on the end, making it possible to start the next writing operation on a new line.

Actions Documentation

Close()

When we open a file for writing, the operating system marks the file as unavailable for other applications. When we are finished writing contents to the file, we must notify the operating system that other files are free to use this file again. To do this, we muse call the Close() action. It is best practice to call Close() as soon as possible after all file contents have been written.

Example Code

use Libraries.System.File
        use Libraries.System.FileWriter

        // Open a file, write a line to it, and then close it.
        File f
        f:SetPath("newFile.txt")
        FileWriter writer
        writer:OpenForWrite(f)

        // Write a line to it
        writer:WriteLine("a line.")

        // Close the file to let the operating system know the file is free.
        writer:Close()

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns a CompareResult. The compare result is either larger if this hash code is larger than the object passed as a parameter, smaller, or equal.

Example Code

use Libraries.Language.Support.CompareResult
        Object o
        Object t
        CompareResult result = o:Compare(t)

Parameters

Return

Libraries.Language.Support.CompareResult: The Compare result, Smaller, Equal, or Larger.

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Example Code

use Libraries.Language.Object
        use Libraries.Language.Types.Text
        Object o
        Text t
        boolean result = o:Equals(t)

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

GetHashCode()

This action gets the hash code for an object.

Example Code

Object o
        integer hash = o:GetHashCode()

Return

integer: The integer hash code of the object.

OpenForWrite(Libraries.System.File file)

Open a file for sequential writing. By "sequential writing," it is meant that it is only possible to write forward in the file. Previously written content cannot be erased, nor can it be modified. This is useful for creating and modifying plain text files, but not so useful for binary files. To manipulate binary files, FileRandomAccess should be used. When this action is used, any previous contents of the file will be destroyed; to preserve previous contents and add on to the end of the file, use OpenForWriteAppend().

Example Code

use Libraries.System.File
        use Libraries.System.FileWriter

        // Open a file for writing, write a line and close it.
        File f
        f:SetPath("myFile.txt") // open myFile.txt for writing (myFile.txt will appear in the working directory of our program)
        FileWriter writer
        writer:OpenForWrite(f)

        // Write two lines.
        writer:WriteLine("first line")
        writer:WriteLine("second line")

        // Close the file.
        writer:Close()

Parameters

OpenForWriteAppend(Libraries.System.File file)

Open a file for sequential writing, but preserve previous file contents. This action is very similar to OpenForWrite(), in that it is only possible to write in one direction, but instead of starting with a fresh file, we may also start with a file that has existing contents. We will append on to the end of the file when we write. If the file does not exist, a new one is created and the behavior is identical to OpenForWrite().

Example Code

use Libraries.System.File
        use Libraries.System.FileWriter
        
        // Open a file, myFile.txt, for writing, but preserve the previous contents.
        File f
        f:SetPath("myFile.txt")
        FileWriter writer
        writer:OpenForWriteAppend(f)
        
        // Add a couple lines (or possibly create a new file with only these contents -- if myFile.txt doesn't exist)
        writer:WriteLine("i added this line today")
        writer:WriteLine("it was pretty easy to do.")

        // Close the file.
        writer:Close()

Parameters

PushToDisk()

When using FileWriter, the contents written to the file are not necessarily written directly to the hard drive immediately. This is for efficiency--as the hard drive (on most systems) is a physically moving platter, it is the slowest component on the system. As such, to save time, file contents are "buffered" and written at a later time. Sometimes, it is necessary to ensure that the contents of our file are written at an exact moment in time. To do this, use the PushToDisk() action. This action should be used sparingly, as it is very inefficient. Typically, file contents are written to disk upon calling Close().

Example Code

use Libraries.System.File
        use Libraries.System.FileWriter

        // Write some content to a file, and call PushToDisk() for extra security.
        File f
        f:SetPath("mySettings.dat")
        FileWriter writer
        writer:OpenForWrite(f)
        writer:WriteLine("value")
        writer:WriteLine("anotherValue")
        
        // Force the operating system to push the lines we have written to disk.
        writer:PushToDisk() // this action may be very slow, depending on how much data needs to be written.

        // Always be sure to call Close(). 
        writer:Close()

Write(text textToWrite)

Writes the given text to the file. This text will be written immediatley after any previously written data (or after any previously existing contents, if the file is opened for appending). If an error occurs during the process, an InputOutputError will be raised.

Example Code

use Libraries.System.File
        use Libraries.System.FileWriter

        // Open a new file and write "abcdefgh" to it.

        File f
        f:SetPath("MySpecialDocument.dat")
        FileWriter writer
        writer:OpenForWrite(f)

        // Write "abcdefgh" to the file in two separate writes.
        writer:Write("abcd")
        writer:Write("efgh")

        // Always call Close().
        writer:Close()

        // The file contents are now "abcdefgh".

Parameters

WriteLine(text textToWrite)

Writes the given text to the file, but also appends a newline character on the end, making it possible to start the next writing operation on a new line. What newline character is inserted depends on the operating system. In conjunction with the FileReader's ReadLine() action, it is possible to quickly write and read contents to files consistently.

Example Code

use Libraries.System.File
        use Libraries.System.FileWriter

        // Write three lines to an existing file.
        File f
        f:SetPath("anExistingFile.txt")
        FileWriter writer
        writer:OpenForWriteAppend(f)

        // Write 3 lines.
        writer:WriteLine("1")
        writer:WriteLine("2")
        writer:WriteLine("3")

        // Close.
        writer:Close()

Parameters