Libraries.System.File Documentation

The File class is used to access and gather information about files on disk. This class can represent either a file or a directory, and provides actions for both manipulation and gathering of file data (such as file name, last time modified, etc). This class is not used for modifying the contents of files, but actions are provided that allow this functionality through other classes, such as OpenForRead(). For more information on modifying the contents of files, see the FileReader, FileWriter and FileRandomAccess classes. Upon creation of a File instance, the File object refers to the program's working directory. The "working directory" of a program is the directory in which a program looks for files. The path that the File instance refers to can be changed using two actions: SetWorkingDirectory and SetPath. The File class only permits setting paths in a relative manner. Paths are relative to the working directory of the given instance of File, which may be changed using the SetWorkingDirectory action. The working directory must be an absolute path and must refer to a directory. See the examples below for common use cases of File.

Example Code

use Libraries.System.File

class Main
action main
    // Read the contents of a file and output them to the screen.
    // This file is in our program's directory.
    File inputFile
    inputFile:SetPath("hello.txt")
    output inputFile:Read() // read and output  all contents to screen.
    
    // Write text to a file, erasing all old contents.
    // This file is located in the C:\Windows folder.
    File outputFile
    outputFile:SetWorkingDirectory("C:\Windows")
    outputFile:SetPath("secret_file.txt")
    outputFile:Write("hello there. this is a new file.")
    
    // Print the working directory of a new File instance. This is, by default,
    // the folder in which our program is stored, i.e.
    // C:\Users\jeff\My Documents\NetBeansProjects\TestProject
    File newFile
    output newFile:GetWorkingDirectory() // this action always returns the working directory.

    // To get the paths a particular File instance refers to, we use the
    // GetPath() and GetAbsolutePath() actions.
    File someFile
    someFile:SetWorkingDirectory("C:\Users\jeff")
    someFile:SetPath("settings.txt")
    output someFile:GetPath() // prints settings.txt.
    output someFile:GetAbsolutePath() // prints C:\Users\jeff\settings.txt
    output someFile:GetWorkingDirectory() // prints C:\Users\jeff

    // Find out if this file is a directory or not.
    File mysteryFile
    mysteryFile:SetPath("images") // assuming a file or directory exists in our working directory called 'images'.
    output "The mystery file object is a file: " + mysteryFile:IsFile()
    output "The mystery file object is a directory: " + mysteryFile:IsDirectory()
end

Inherits from: Libraries.Language.Object

Actions Documentation

Close()

If this file has been opened for reading, writing, or random access (see the actions OpenForRead(), OpenForWrite(), OpenForWriteAppend() and OpenForRandomAccess()), this action should be called to "close" the file. "Closing" a file means releasing it back to the operating system so that other programs may use it.

Example

use Libraries.System.File
use Libraries.System.Blueprints.FileWriterBlueprint

// Open a file for sequential writing and write a few lines. Then, close it.
File f
f:SetWorkingDirectory("/Users/jeff/")
f:SetPath("dictionary.txt")
FileWriterBlueprint writer = f:OpenForWrite()

// Create a small dictionary.
writer:WriteLine("abstraction")
writer:WriteLine("kafkaesque")
writer:WriteLine("quarry")

f:Close() // we're done with the file

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Example

Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

Copy(Libraries.System.File copy)

Copy the file (or directory) specified to the new location specified. The behavior of this action is highly dependent on the platform and file system; always check the return value to ensure success.

Parameters

Return

boolean: True if the move succeeds; false otherwise.

Example

use Libraries.System.File

// Move a file from one directory to another.
File f
f:SetPath("Untitled.mp3")

File copy
copy:SetPath("Jeff.mp3")
boolean moveSucceeded = f:Copy(copy)
if moveSucceeded
    output "Copy succeeded."
else
    output "Copy failed."
end

Copy(Libraries.System.File file, boolean recursive)

Copy the file (or directory) specified to the new location specified. The behavior of this action is highly dependent on the platform and file system; always check the return value to ensure success. If the recursive flag is set, and Copy is called on a folder, then all subfolders and files are also copied.

Parameters

Return

boolean: True if the move succeeds; false otherwise.

Example

use Libraries.System.File

// Move a file from one directory to another.
File f
f:SetPath("folder")

File copy
copy:SetPath("other")
boolean moveSucceeded = f:Copy(copy, true)
if moveSucceeded
    output "Copy succeeded."
else
    output "Copy failed."
end

CreateDirectories()

Create the directory specified in the path by this File object. This can be used to create a single directory and all parents. As an example, if the path "C:\blah\bb" does not already exist under "C:\", this method creates all three in this path: C:\blah\bb\foo

Return

boolean: True if directory creation succeeds; false otherwise.

Example

use Libraries.System.File

// Create a directory in /Users/jeff called "oldMusic".
File oldMusicDir
oldMusicDir:SetWorkingDirectory("/Users/jeff")
oldMusicDir:SetPath("oldMusic")
oldMusicDir:CreateDirectories()

CreateDirectory()

Create the directory specified in the path by this File object. This can only be used to create a single directory; it is not possible to create an entire path using this action. As an example, if the path "C:\blah\bb" does not already exist under "C:\", we cannot create all three directories in this path: C:\blah\bb\foo Rather, we would create each individually (see example below).

Return

boolean: True if directory creation succeeds; false otherwise.

Example

use Libraries.System.File

// Create a directory in /Users/jeff called "oldMusic".
File oldMusicDir
oldMusicDir:SetWorkingDirectory("/Users/jeff")
oldMusicDir:SetPath("oldMusic")
oldMusicDir:CreateDirectory()

Delete(boolean recursive)

Delete the path specified by this File object. This operation does not send items to the appropriate recycle bin or trash can folder on the system, and it cannot be easily undone (if at all). This operation can be used to delete single files or directories, whether they are empty or not. A value of false is the same as Delete() with no parameters.

Parameters

  • boolean recursive

Example

use Libraries.System.File

// Create a directory and delete it.
File myDir
myDIr:SetWorkingDirectory("C:\Users\jeff\My DOcuments\")
myDir:SetPath("A_New_Folder")
myDir:CreateDirectory()
boolean ok = myDir:Delete(true) // delete it

if ok
    output "deletion succeeded."
else
    output "deletion failed."
end

Delete()

Delete the path specified by this File object. This operation does not send items to the appropriate recycle bin or trash can folder on the system, and it cannot be easily undone (if at all). This operation can only be used to delete single files or empty directories.

Return

boolean: True if the operation succeeds; false otherwise.

Example

use Libraries.System.File

// Create a directory and delete it.
File myDir
myDIr:SetWorkingDirectory("C:\Users\jeff\My DOcuments\")
myDir:SetPath("A_New_Folder")
myDir:CreateDirectory()
boolean ok = myDir:Delete() // delete it

if ok
    output "deletion succeeded."
else
    output "deletion failed."
end

Equals(Libraries.Language.Object object)

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

Parameters

Return

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

Example

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

Exists()

Test whether or not the path this File object refers to exists, that is, whether or not the path refers to a valid file or directory.

Return

boolean: True if the file or directory exists; false otherwise.

Example

use Libraries.System.File

// Does a folder called "Windows" exist under C:\? On Windows systems, it will;
// on other systems, it will not.
File winDir
winDir:SetWorkingDirectory("C:\")
winDir:SetPath("Windows")
output "Does 'C:\Windows' exist?  " + winDir:Exists() // on Windows systems, will output  "Does 'C:\Windows' exist? true"

GetAbsolutePath()

Get the absolute path this File object represents. Essentially, this is the same concept as GetPath, but the path is "absolute", that is, it is NOT dependent on the working directory of a File object. The absolute path is the working directory of File and the path of File concatenated together.

Return

text: the absolute path this File object represents.

Example

use Libraries.System.File
// Construct a file object to refer to "C:\Windows\System32".
File sys
sys:SetWorkingDirectory("C:\Windows")
sys:SetPath("System32")
output sys:GetPath() // prints "System32"
output sys:GetAbsolutePath() // prints "C:\Windows\System32"

GetDirectoryListing()

Obtain a list of files and directories in the directory specified by this File object. If this File object does not represent a directory, undefined is returned.

Return

Libraries.Containers.Array: an indexable collection of File objects representing files and folders in the path of this File object. Returns undefined if this File object does not point to a directory.

Example

use Libraries.System.File
use Libraries.Containers.Array

// Get the first item (alphabetical order) listed in C:\.
File cDrive
cDrive:SetWorkingDirectory("C:\")
Array<File> items = cDrive:GetDirectoryListing()
File f0 = items:Get(0)
output f0:GetPath()

GetFileExtension()

Obtain the file extension of the path this File object represents. A file extension is any text after the last '.' character in a path; files and directories can have extensions. For example, the path C:\Users\jeff\hello.txt has the extension "txt". Similarly, the path below, although it represents a directory on Macintosh systems, has the extension "app". /Applications/Sodbeans.app If no '.' character exists in the path, there is no extension in the path, and an empty string is returned.

Return

text: The file extension or "" if no extension is present. The '.' character will not be present in the return value.

Example

use Libraries.System.File

// Get the extension of a music file.
File musicFile
musicFile:SetWorkingDirectory("C:\Users\jeff\Music")
musicFile:SetPath("Untitled.mp3")
output musicFile:GetFileExtension() // prints "mp3" on all systems.

// Get the extension of a directory.
File appDir
appDir:SetWorkingDirectory("/Applications/")
appDir:SetPath("TextEdit.app")
output appDir:GetFileExtension() // prints "app" on all systems.

GetFileName()

Obtain the last part of the path name for this File object. This will be the last file or directory in the path. For example, if we had a File object that represented the path C:\Users\jeff\My Documents this action would return "My Documents." Similarly, if we had a File object that represented the path C:\Users\jeff\My Documents\homework.doc this action would return "homework.doc". This action always returns the last thing in the path, so if our path is simply "C:\", this action will return "C:\". If our path is "/", this action will return an empty string ("").

Return

text: The last portion of the path name. This may be a file name, directory name, or drive letter.

Example

use Libraries.System.File

// Get the file name from this path.
text path = "C:\Program Files\Sodbeans\bin\sodbeans.exe"
File file
file:SetWorkingDirectory("C:\Program Files\Sodbeans\bin\")
file:SetPath("sodbeans.exe")
output file:GetFileName() // will output  "sodbeans.exe". (on any system)

GetFileSize()

Get the total size of the file represented by this File object. This is the total number of bytes this file contains, but doesn't necessarily say how much disk space this file takes on disk. This action only returns a meaningful value for files; for directories, the value is always 0.

Return

number: the file size in bytes. This may be 0 if the file does not exist, the path is a directory, or the path is invalid.

Example

use Libraries.System.File

// How big is the "notepad" program on Windows?
File notepad
notepad:SetWorkingDirectory("C:\Windows")
notepad:SetPath("notepad.exe")
output "Notepad is " + notepad:GetFileSize() + " bytes."

GetFreeDiskSpace()

Obtain the amount of unallocated hard drive space on the drive this path represents. For example, if our path starts with "C:\" on Windows systems, this will return the amount of free disk space on the "C" drive. On Unix and Mac OS X systems, the drive being referenced depends greatly on the system configuration.

Return

number: the amount of unallocated hard drive space in bytes. This value will always be a whole number.

Example

use Libraries.System.File

// How much disk space is available on C in gigabytes?
File cDir
cDir:SetWorkingDirectory("C:\")
number amount = cDir:GetFreeDiskSpace() / 1024 / 1024 / 1024 // conversion from bytes to kilobytes, kilobytes to megabytes, megabytes to gigabytes
output "Drive C has " + amount + " GB free."

// How much disk space is available on the root drive? (Mac and Unix/Linux only).
File root
root:SetWorkingDirectory"/")
amount = root:GetFreeDiskSpace() / 1024 / 1024 / 1024 // conversion from bytes to kilobytes, kilobytes to megabytes, megabytes to gigabytes
output "The root drive has " + amount + " GB free."

GetHashCode()

This action gets the hash code for an object.

Return

integer: The integer hash code of the object.

Example

Object o
integer hash = o:GetHashCode()

GetLastModifiedDate()

Obtain the date and time this file or directory was last modified. Typically, this is the date and time either the contents of the file (or directory) changed, or it was renamed.

Return

Libraries.System.DateTime: the modified date and time as a DateTime object, or undefined if the path represented by this File object does not exist.

Example

use Libraries.System.File
use Libraries.System.DateTime

// When was "Program Files" last modified?
File programFiles
programFiles:SetWorkingDirectory("C:\Program Files")
DateTime date
if date not= undefined
    output "Program files was last modified on" + date:GetMonth() + "/" + date:GetDayOfMonth() + "/" + date:GetYear()
else
    output "Program files does not have any data. This is likely not a Windows system."
end

GetParentDirectory()

Get the parent directory of this particular File object. The parent directory is the directory immediately above the file or directory this File object points in to. For example, if our File object represents the path C:\Program Files\Sodbeans the parent directory is "C:\Program Files" If our File object represents a file, such as /Users/jeff/hello.txt the parent directory is /Users/jeff. In general, it is the path up to the last forward or backward slash. If there is no parent directory, as in the case of paths such as "C:\" or "/", undefined is returned.

Return

Libraries.System.File: The parent directory of this File object as a new File object, or undefined if no parent exists.

Example

use Libraries.System.File

// Get the parent directory of our working directory (remember, File points to our working directory if we don't set a path).
File workingDir
File parentDir = workingDir:GetParentDirectory()

// Is there a parent directory?
if parentDir not= undefined
    output parentDir:GetPath()
else
    output "There is no parent to our working directory."
end

GetPath()

Get the path associated with this File object. If a File class is instantiated and the action SetPath has been called, then this will return an empty string. Otherwise, it will return the relative path set for this File instance. (Relative to the current working directory).

Return

text: the path this file represents, or an empty string.

Example

use Libraries.System.File

// Set a path and get it back. This File object ultimately represents the
// path "/Users/jeff/Music"
File someFile
someFile:SetWorkingDirectory("/Users/jeff/")
someFile:SetPath("Music")
output someFile:GetPath() // prints "Music"

GetTotalDiskSpace()

Obtain the total amount of hard drive space on the drive this path represents. This is the total capacity of the disk. For example, if our path starts with "C:\" on Windows systems, this will return the capacity of the "C" drive. On Unix and Mac OS X systems, the drive being referenced depends greatly on the system configuration.

Return

number: the capacity of the hard disk in bytes. This value will always be a whole number.

Example

use Libraries.System.File

// How much disk space is available on C in gigabytes?
File cDir
cDir:SetWorkingDirectory("C:\")
number amount = cDir:GetTotalDiskSpace() / 1024 / 1024 / 1024 // conversion from bytes to kilobytes, kilobytes to megabytes, megabytes to gigabytes
output "Drive C has a total capacity of " + amount + " GB."

// How much disk space is available on the root drive? (Mac and Unix/Linux only).
File root
root:SetWorkingDirectory("/")
amount = root:GetTotalDiskSpace() / 1024 / 1024 / 1024 // conversion from bytes to kilobytes, kilobytes to megabytes, megabytes to gigabytes
output "The root drive has a total capacity of  " + amount + " GB."

GetWorkingDirectory()

This action returns the "working directory" of our program. The "working directory" is the directory our program looks in by default when looking for files that aren't specified by an absolute path. For example, if we wish to open the path "dictionary.txt," this would refer to a file named "dictionary.txt" in our working directory. By default, the working directory is the directory where the program is stored.

Return

text: The directory our application is working in.

Example

use Libraries.System.File

File myFileObject
output "The working directory of this program is " + myFileObject:GetPath()

IsDirectory()

Test whether or not the path this File object refers to is a "directory." A directory is a folder on the file system that contains other files or directories.

Return

boolean: True if the path of this File object is a directory; False if it is a directory or the path is invalid. (see Exists())

Example

use Libraries.System.File

// On most systems, the path './' refers to the current directory.
// Is the current directory a directory?
File currentDir
currentDir:SetPath("./")
output "Are we in a directory? " + currentDir:IsDirectory() // On most systems, will output  "Are we in a directory? true"

// On Windows systems, is "C:\" a directory?
File cDrive
cDrive:SetWorkingDirectory("C:\")
output "Is C:\ a directory? " + cDrive:IsDirectory() // On Windows systems, will output  "Is C:\ a directory? true"

IsFile()

Determine whether or not the path this File object refers to is a "file," that is, an entity on the file system that is not a directory.

Return

boolean: True if the path of this File object is a file; False if it is a directory or the path is invalid. (see Exists()).

Example

use Libraries.System.File

// Is C:\Windows a file?
File winDir
winDir:SetWorkingDirectory("C:\Windows")
output "Is C:\Windows a file? " + winDir:IsFile() // Will output  'Is C:\Windows a file? false'

// Is C:\Windows\System32\kernel32.dll a file?
File kernel32
kernel32:SetWorkingDirectory("C:\Windows\system32\")
kernel32:SetPath("ernel32.dll")
output "Is C:\Windows\System32\kernel32.dll a file? " + kernel32:IsFile() // On Windows systems, will output  "Is C:\Windows\System32\kernel32.dll a file? true"

IsHidden()

Test whether or not the path this File object refers to is a file with the "hidden" attribute set. "Hidden" files set an attribute, called "hidden," which hides them from the user by default. This attribute is not supported by all operating systems, so it is possible that this action will always return false on some systems.

Return

boolean: True if the path of this File object is a file with the hidden attribute; false otherwise.

Example

use Libraries.System.File

// On Windows systems, the "user32.dll" file is hidden.
File user32
user32:SetWorkingDirectory("C:\Windows\System32")
user32:SetPath("user32.dll")
output "Is user32.dll hidden? " + user32:IsHidden() // On Windows systems, will output  "Is user32.dll hidden? true"

Move(text newPath)

Move the file (or directory) specified to the new path specified. The behavior of this action is highly dependent on the platform and file system; always check the return value to ensure success.

Parameters

  • text newPath: the new path to move the file to. May be an absolute path or a relative path.

Return

boolean: True if the move succeeds; false otherwise.

Example

use Libraries.System.File

// Move a file from one directory to another.
File f
f:SetWorkingDirectory("/Users/jeff/Music/")
f:SetPath("Untitled.mp3")
boolean moveSucceeded = f:Move("/Users/jeff/oldMusic/Untitled.mp3")
if moveSucceeded
    output "Move succeeded."
else
    output "Move failed."
end

// Move can also be used to rename a file.
File renameMe
renameMe:SetWorkingDirectory("/Users/jeff/Music/")
renameMe:SetPath("Untitled.mp3")
moveSucceeded = renameMe:Move("/Users/jeff/Music/Toccata and Fugue.mp3")
if moveSucceeded
    output "Move succeeded."
else
    output "Move failed."
end

OpenForRandomAccess()

Open this file for random access. "Random access" implies that reading and/or writing to the file can occur in a non-sequential fashion. See FileRandomAccessBlueprint's documentaiton for more information.

Return

Libraries.System.Blueprints.FileRandomAccessBlueprint: A FileRandomAccessBlueprint, sufficient for random access to the file's contents.

Example

use Libraries.System.File
use Libraries.System.Blueprints.FileWriterBlueprint

// Open a file for sequential writing and write a few lines.
File f
f:SetWorkingDirectory("/Users/jeff/")
f:SetPath("dictionary.txt")
FileWriterBlueprint writer = f:OpenForWrite()

// Create a small dictionary.
writer:WriteLine("abstraction")
writer:WriteLine("kafkaesque")
writer:WriteLine("quarry")

f:Close() // we're done with the file, see Close() documentation.