Fileclassfile.h[108]

The File intrinsic class provides access to files in the external file system. This lets you create, read, and write files. The class supports text files (with translations to and from local character sets), "data" files (using the special TADS 2 binary file format), and "raw" files (this mode lets you manipulate files in arbitrary text or binary formats by giving you direct access to the raw bytes in the file).

intrinsic class File :   Object

Superclass Tree   (in declaration order)

File
        Object

Subclass Tree  

(none)

Global Objects  

(none)

Summary of Properties  

(none)

Summary of Methods  

closeFile  getCharacterSet  getFileSize  getPos  readBytes  readFile  setCharacterSet  setPos  setPosEnd  writeBytes  writeFile 

Inherited from Object :
getPropList  getPropParams  getSuperclassList  isClass  isTransient  ofKind  propDefined  propInherited  propType  valToSymbol 

Properties  

(none)

Methods  

closeFile ( )file.h[226]

Close the file. Flushes any buffered information to the underlying system file and releases any system resources (such as share locks or system buffers) associated with the file. After this routine is called, no further operations on the file can be performed (a FileClosedException will be thrown if any subsequent operations are attempted).

It's not strictly necessary to call closeFile() on a File, since the system will automatically do this work when the File object becomes unreachable and is discarded by the garbage collector. However, it is good practice to close a file explicitly by calling this method as soon as the program reaches a point at which it knows it's done with the file, because garbage collection might not run for a significant amount of time after the program is actually done with the file, in which case the system resources associated with the file would be needlessly retained for this extended time.

getCharacterSet ( )file.h[198]
get the CharacterSet object the File is currently using; returns nil for a non-text file

getFileSize ( )file.h[375]
get the size in bytes of the file

getPos ( )file.h[319]
Get the current read/write position in the file. Returns the byte offset in the file of the next byte to be read or written. Note that this value is an offset, so 0 is the offset of the first byte in the file.

readBytes (byteArr, start?, cnt?)file.h[299]
Read bytes from the file into the given ByteArray object. This can only be used for a file opened in 'raw' mode. If 'start' and 'cnt' are given, they give the starting index in the byte array at which the bytes read are to be stored, and the number of bytes to read, respectively; if these are omitted, one byte is read from the file for each byte in the byte array.

Returns the number of bytes actually read into the byte array, which will be less than or equal to the number requested. If the number read is less than the number requested, it means that the end of the file was encountered, and only the returned number of bytes were available.

readFile ( )file.h[256]
Read from the file. Returns a data value that depends on the file mode, as described below, or nil at end of file.

If the file is open in text mode, this reads a line of text from the file and returns a string with the text of the line read. A line of text is a sequence of characters terminated with a line-ending sequence, which is a carriage return, line feed, CR/LF pair, LF/CR pair, or a Unicode line terminator character (0x2028) if the file is being read with one of the Unicode encodings. If the line read ends in a line-ending sequence, the returned text will end in a '\n' character, regardless of which of the possible line-ending sequences is actually in the file, so the caller need not worry about the details of the external file's format. Every line read from the file will end in a '\n' except possibly the last line - if the file does not end with a line-ending sequence, then the last line read from the file will not end in a '\n' character. All bytes read from the file will be mapped to characters through the CharacterSet object currently in effect in the file, so the returned string will always be a standard Unicode string, regardless of the byte encoding of the file.

If the file is open in 'data' mode, this reads one data element using the private tads-specific data format. The result is a value of one of the types writable with writeFile() in 'data' mode. In order to read a 'data' file, the file must have been previously written in 'data' mode.

setCharacterSet (charset)file.h[206]
Set the CharacterSet object the File is to use from now on. This is not meaningful except for text files. 'charset' must be a CharacterSet object; in particular note that a character set name given as a string is not allowed here.

setPos (pos)file.h[339]
Set the current read/write position in the file. 'pos' is a byte offset in the file; 0 is the offset of the first byte.

For files in 'text' and 'data' modes, a caller should NEVER set the file position to any value other than a value previously returned by getPos(), because other positions might violate the format constraints. For example, if you move the file position to a byte in the middle of a line-ending sequence in a text file, subsequent reading from the file might misinterpret the sequence as something other than a line ending, or as an extra line ending. If you move the position in a 'data' file to a byte in the middle of an integer value, reading from the file would misinterpret as a data type tag a byte that is part of the integer value instead. So it is never meaningful or safe to set an arbitrary byte offset in these file formats; only values known to be valid by virtue of having been returned from getPos() can be used here in these modes.

setPosEnd ( )file.h[348]
Set the current read/write position to the end of the file. This can be used, for example, to open a 'data' mode file for read/write/keep access (keeping the contents of an existing file) and then adding more data after all of the existing data in the file.

writeBytes (byteArr, start?, cnt?)file.h[311]
Write bytes from the ByteArray object into the file. This can only be used for a file opened in 'raw' mode. If 'start' and 'cnt' are given, they give the starting index in the byte array of the bytes to be written, and the number of bytes to write, respectively; if these are omitted, all of the bytes in the array are written.

No return value; if an error occurs writing the data, a FileIOException is thrown.

writeFile (val)file.h[283]
Write to the file. Writes the given value to the file in a format that depends on the file mode, as described below. No return value; if an error occurs writing the data, this throws a FileIOException.

If the file is open in text mode, this writes text to the file, converting the given value to a string if necessary (and throwing an error if such a conversion is not possible), and translating the string to be written to bytes by mapping the string through the CharacterSet object currently in effect for the file. Note that no line-ending characters are automatically added to the output, so if the caller wishes to write line terminators, it should simply include a '\n' character at the end of each line.

If the file is open in 'data' mode, this writes the value, which must be a string, integer, enum, or 'true' value, in a private tads-specific data format that can later be read using the same format. The values are converted to the private binary format, which is portable across platforms: a file written in 'data' mode on one machine can be copied (byte-for-byte) to another machine, even one that uses different hardware and a different operating system, and read back in 'data' mode on the new machine to yield the original values written.

TADS 3 Library Manual
Generated on 4/11/2008 from TADS version 3.0.16