Fileclass | file.h[131] |
Superclass Tree | Subclass Tree | Global Objects | Property Summary | Method Summary | Property Details | Method Details |
intrinsic class
File : Object
File
Object
closeFile
digestMD5
getCharacterSet
getFileMode
getFileSize
getPos
packBytes
readBytes
readFile
setCharacterSet
setFileMode
setPos
setPosEnd
sha256
unpackBytes
writeBytes
writeFile
Inherited from Object
:
callInherited
createIterator
createLiveIterator
forEach
getPropList
getPropParams
getSuperclassList
isClass
isTransient
mapAll
ofKind
propDefined
propInherited
propType
valToSymbol
closeFile ( ) | file.h[292] |
If the game is running in web server mode, the file might be on a remote storage server. In this case, if the file was opened with write access, closing it will send the file to the storage server.
Note that this method can throw an error, so you shouldn't consider updates to the file to be "safe" until this method returns successfully. On many systems, writes are buffered in memory, so closing the file can involve flushing buffers, which can trigger the same sorts of errors that can happen with ordinary writes (running out of disk space, physical media defects, etc). In addition, when the file is on a remote network storage server, closing a file opened with write access transmits the file to the storage server, which can encounter network errors.
You should always explicitly close files when done with them. This is especially important when writing to a file, because many systems buffer written data in memory and don't write changes to the physical media until the file is closed. This means that updates can be lost if the program crashes (or the computer loses power, etc) while the file is still open. Closing the file as soon as you're done with it reduces the chances of this kind of data loss. It also helps overall system performance to release resources back to the operating system as soon as you're done with them.
If you *don't* close a file, though, the system will close it automatically when the File object becomes unreachable and is deleted by the garbage collector. It's considered bad form to depend on this for the reasons above, and it's also problematic because you won't have any way of finding out if an error should happen on close.
digestMD5 (length?) | file.h[563] |
Returns a string of 32 hex digits giving the digest result.
This can only be used on files opened in raw mode with read access.
getCharacterSet ( ) | file.h[241] |
getFileMode ( ) | file.h[458] |
getFileSize ( ) | file.h[452] |
getPos ( ) | file.h[396] |
packBytes (format, ...) | file.h[522] |
'format' is the format string, and the remaining arguments are the values to be packed.
Returns the number of bytes written to the file. (More precisely, returns the final file position as a byte offset from the starting file pointer. If a positioning code like @ or X is used in the string, it's possible that more bytes were actually written.)
See Byte Packing in the System Manual for details.
readBytes (byteArr, start?, cnt?) | file.h[365] |
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[322] |
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 doesn't end with a line-ending sequence, then the last line read from the file won't 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[251] |
setFileMode (mode, charset?) | file.h[501] |
If the mode is FileModeText, 'charset' is the character set mapping to use for the file; this can be given as a CharacterSet object, or as a string giving the name of a character set. If the value is nil or the argument is omitted, the local system's default character for file contents is used. The 'charset' parameter is ignored for other modes.
setPos (pos) | file.h[416] |
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[425] |
sha256 (length?) | file.h[549] |
Returns a string of 64 hex digits giving the hash result.
This can only be used on files opened in raw mode with read access.
unpackBytes (format) | file.h[535] |
'format' is the format string. The function reads bytes from the current location in the file and translates them into data values according to the format string, returning a list of the unpacked values.
Refer to Byte Packing in the System Manual for details.
writeBytes (source, start?, cnt?) | file.h[388] |
The source object must be one of the following object types:
File: the contents of the given source file are copied to 'self'. 'start' is the starting seek position in the source file; if omitted, the current seek position is the default. 'cnt' is the number of bytes to copy; if omitted, the file is copied from the given starting position to the end of the file.
ByteArray: the bytes of the byte array are copied to the file. 'start' is the starting index in the byte array; if omitted, the default is the first byte (index 1). 'cnt' is the number of bytes to copy; if omitted, bytes are copied from the start position to the end of the array.
No return value; if an error occurs writing the data, a FileIOException is thrown.
writeFile (val) | file.h[349] |
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 isn't 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.