File Object

The File object provides basic file handling functions such as checking for a file's existence, opening a file for reading or writing, and removing a file. In general paths that include directories can be separated using / (which doesn't need escaping), even on Windows.

Example:

var file = File.open("C:\\testdata\\input.txt", "r");
file.encoding = "system"; // Should only be needed for some Windows AUTs
var text = file.read();
inputField.setText(text);

The default file encoding is "utf-8" which is the best encoding to use for text files.

file.close()

This method closes the file object it is called on. Once closed, a file object cannot be read from or written to.

File.copy(source, target)

This function copies the file source to target. If this fails an exception is thrown.

The copy fails if target already exists. If desired, Boolean File.remove(fileName) can be used beforehand to make room for the copy.

String file.encoding

This property defines the encoding to use when reading or writing files. The default encoding is "utf-8". For AUTs that don't support UTF-8 (such as some Windows applications), setting the encoding to "system" may prove helpful since this makes Squish use the current system locale. Other possible values are "ucs-2" (2 byte Unicode, for reading UTF-16 on Windows) and "latin1" (also known as ISO 8859-1) which includes the US-ASCII range.

This property should be set before doing any reading or writing.

Boolean File.exists(fileOrDirectory)

This function returns true if the specfied fileOrDirectory exists; otherwise it returns false. The fileOrDirectory may include an absolute or relative path, or no path, in which case the current working directory is used.

File File.open(fileName)

File File.open(fileName, mode)

This function tries to open the specified fileName (which may include an absolute or relative path, or no path, in which case the current working directory is used). The optional mode parameter defaults to "r" (open for reading). If the mode is specified it must be: "a" (open for append), or "r" (open for reading), or "w" (open for writing). If the fileName cannot be opened a catchable exception is thrown.

Once a file has been successfully opened its methods can be called. For files opened in append or write mode the file.write(string) method can be called, and for files opened in read mode the String file.read() and String file.readln() methods can be called. And for any opened file, the file.close() method can be called.

StringList File.glob(pattern, [pattern...])

This function returns the list of paths matching any of the given patterns.

String file.read()

This method reads in the entire contents of the file object returned by the File File.open(fileName) function—providing the file was opened in read mode. The file's content is assumed to be plain text using the UTF-8 encoding (unless the file.encoding property is changed).

String file.readln()

This method reads in the next line from the file object returned by the File File.open(fileName) function—providing the file was opened in read mode. The file's content is assumed to be plain text using the UTF-8 encoding (unless the file.encoding property is changed). Each line is returned without any end of line characters, and if an attempt to read beyond the last line is made, null is returned.

Boolean File.remove(fileName)

This function tries to remove the specified fileName (which may include an absolute or relative path, or no path, in which case the current working directory is used). If the file was successfully removed the function returns true; otherwise it returns false.

String File.separator

The global File object's read-only separator property holds the file separator used by the operating system. For example, on Windows it holds, "\", and on Unix-like systems, "/".

Number File.size(fileName)

This function returns the size of the specified fileName (which may include an absolute or relative path, or no path, in which case the current working directory is used).

file.write(string)

This method writes the given string to the file object returned by the File File.open(fileName) function—providing the file was opened in append or write mode. The string is written using the UTF-8 encoding (unless the file.encoding property is changed).