File class

The File class provides functionality for reading and writing binary and text files. A File can be instantiated as an object, giving the script developer complete flexibility when reading and writing files. In addition, the File class provides a set of static convenience functions for reading and writing files in one go.

Enum AccessMode

The enum AccessMode is used in conjunction with File.open() to specify the mode in which the file is opened. The access mode is specified by OR-ing together values from the following list.

Access mode	Description
File.ReadOnly	Opens the file in read-only mode
File.WriteOnly	Opens the file in write-only mode; if this flag is used with Append, the file is not truncated; but if used on its own (or with Truncate), the file is truncated
File.ReadWrite	Opens the file in read/write mode; the file is not truncated
File.Append	Opens the file in append mode; you must actually use (WriteOnly \| Append) to make the file writable and to go into append mode; this mode is very useful when you want to write something to a log file: the file index is set to the end of the file; note that the result is undefined if you position the file index manually using at() in append mode
File.Truncate	Truncates the file
File.Translate	Enables line break translation (carriage return and linefeed) for text files to platform-specific conventions

Static functions

exists( fileName : String ) : Boolean

Returns true if fileName exists; otherwise returns false.

remove( fileName : String )

Deletes the file fileName if possible; otherwise throws an exception.

isFile( fileName : String ) : Boolean

Returns true if fileName is a file; otherwise returns false.

isDir( fileName : String ) : Boolean

Returns true if fileName is a directory; otherwise returns false.

isType( fileName : String, ext : String ) : Boolean

Returns true if the job matches the specified file type, specified as a filename extension, and false otherwise.

A file matches if its filename extension and/or its Mac file type (after conversion) match the specified filename extension. A folder matches if any of the files at the topmost level inside the folder match the specified type. These semantics are similar to those of matching cross-platform file types in filter connections.

Checking for arrival

This function checks if a file has "arrived":

If the file doesn't exist or can't be opened with exclusive read access, return false.
Note the file's size, and wait for a specified period of time ("stability period").
If the file's size has changed during the period, return false.
If the file can't be opened with exclusive read access after the period, return false.
Otherwise return true.

hasArrived( fileName : String, stabilitySeconds : Number ) : Boolean [static]

hasArrived( stabilitySeconds : Number ) : Boolean

toNativeSeparators( fileName : String ) : String

fromNativeSeparators( fileName : String ) : String

Returns true if it can be assumed that the file has arrived according to the heuristic describe above; otherwise returns false. The stability period is specified in seconds (as a floating point number).

The length of the required stability period depends on the nature and size of the file, on the process writing the file, and on the performance and workload of the computer system(s) involved. In most cases a stability period of 1 second is both sufficient and acceptable (in terms of delay). When the file is produced by a slow process or transferred across a slow network, a much longer stability period may be required.

Returns fileName with the '/' separators converted to separators that are appropriate for the underlying operating system.

Returns fileName using '/' as file separator.

Note:

A hasArrived() function often returns only after a delay of at least the stability period. However if it can be determined right away that the file has not yet arrived, the function returns immediately. Thus it is never acceptable to invoke a hasArrived() function in a tight loop.

The following table describes the two most important use cases for dealing with an external application through the hasArrived() functions. In fact, the guidance presented in the table does not depend on the employed arrival/ready detection mechanism.

Model	Description	Implementation
Synchronous	If the external process is synchronous, resource-intensive and hosted on the same computer as Switch, the jobArrived entry point should block until the process is finished (so that Switch can correctly manage the number of external processes running in parallel)	jobArrived entry point contains a waiting loop that repeatedly calls hasArrived() followed by Environment.sleep() to introduce additional delay
Asynchronous	If the external process is asynchronous (i.e. you want to feed it the next job even if the previous job hasn't been processed), if it depends on user interaction, or if it potentially takes a long time without using a lot of resources on the local computer, the jobArrived entry point should return immediately and leave the follow-up to the timerFired entry point	timerFired entry point simply calls hasArrived() once, since it is automatically executed repeatedly with a predefined interval

Static Text I/O functions

read( fileName : String, codec : String ) : String

Reads and returns the contents of the file fileName if possible; otherwise throws an exception.

The optional argument codec specifies the text encoding used to read the file; see text encoding.

write( fileName : String, content : String, codec : String )

Writes the string content to the file fileName if possible (completely replacing the original contents if the file already exists); otherwise throws an exception.

The optional argument codec specifies the text encoding used to write the file contents; see text encoding.

Static Binary I/O functions

The functions presented in this section read and write sequences of bytes (rather than text streams). Hence there is no need to specify a codec (see text encoding).

readByteArray( fileName : String ) : ByteArray: Reads and returns the content of the file fileName if possible; otherwise throws an exception.
writeByteArray( fileName : String, content : ByteArray ): Writes the content to the file fileName if possible (completely replacing the original contents if the file already exists); otherwise throws an exception.

Constructor

File( fileName : String, codec : String )

Creates a file object with the fileName. If fileName is missing or is not a String, an exception is thrown.

The optional argument codec specifies the text encoding used to read or write the file contents; see text encoding.

Properties

The File object's properties are read-only.

name : String: The name of the file including the extension.
path : String: The path of the file.
fullName : String: The fullName of the file, including path, name, and extension.
baseName : String: The name of the file, excluding its path and extension.
extension : String: The file name's extension.
symLink : String: The expansion of the symlink if the file is a symlink; otherwise empty.
exists : Boolean: True if the file exists; otherwise false.
readable : Boolean: True if the file is readable; otherwise false.
writable : Boolean: True if the file is writable; otherwise false.
executable : Boolean: True if the file is executable; otherwise false.
hidden : Boolean: True if the file is hidden; otherwise false.
eof : Boolean: True if reading has reached the end of the file; otherwise false.
created : Date: The creation time of the file.
lastModified : Date: The last modification time of the file.
lastRead : Date: The last time the file was read.
size : Number: The size of the file, in bytes.
codec: String: The codec being used for reading and writing the file's contents; see text encoding.

Member functions

open( accessMode : Number )

Opens the file in the mode accessMode (see enum AccessMode) if possible; otherwise throws an exception.

For example:

profile.open(File.ReadOnly);

Opens a file for reading only.

jobfile.open(File.WriteOnly|File.Translate);

Opens a file for writing and enables line break translation.

close()

Closes the file.

remove()

Deletes the file if possible; otherwise throws an exception.

Member Text I/O functions

readChar() : Number: Reads one character from the file if possible; otherwise throws an exception. The character is represented as a 16-bit Unicode code point.
read() : String: Returns the entire content of the file as a string if it can be read; otherwise throws an exception.
readLine() : String: Reads one line from file if possible; otherwise throws an exception. Retains any trailing whitespace.
readLines() : String[ ]: Returns the contents of the file as an Array of strings, one for each line. Linebreaks are stripped from the strings. If the file could not be read, an exception is thrown.
writeChar( char : Number ): Writes one character to the file if possible; otherwise throws an exception. The character is represented as a 16-bit Unicode code point.
write( data : String, length : Number ): Writes length number of characters from data to the file if possible; otherwise throws an exception.
writeLine( data : String ): Writes the line data to the file and adds a linebreak. If the file could not be written error is returned.

Member Binary I/O functions

The functions presented in this section ignore the file's codec (see text encoding). Never mix these binary I/O function with any of the text-oriented I/O functions on the same file. Violating this rule has unpredictable results.

readByte() : Number: Reads one byte from the file if possible; otherwise throws an exception.
writeByte( byte : Number ): Writes one byte to the file if possible; otherwise throws an exception.