These functions support the reading and writing of data to external files. Such functions could be useful for communication between different saved games, logging information for debugging during development, saving information about characters between entirely different games, or any other general purpose. Files must not remain open while the user is allowed to save a game, because file pointers will not be saved. You must open and close all files within the saved game, or take other measures to ensure that the user does not save or restore a game while a file is open.
Functions
function FileOpen (FilenameString, ModeString)
Opens a file.
Parameters
FilenameString | | Filename in the Windows file system. (Remember to use \\ inside strings to represent the \ character, or use / instead.) | ModeString | | A string which is one of the following codes: r, w, a, rb, wb, ab, r+, w+, a+, r+b, w+b or a+b. The code letters stand for read, write, append and binary, and the plus specifies that the file can be both read and written. | Term | Definition | | read | opens an existing file for reading | | write | creates a new file or truncates an existing file for writing | | append | creates a new file or appends an existing file for writing, and repositions the write pointer to the end of the file before each write operation | | binary | specifies binary mode instead of text mode so \n characters will not be translated automatically into DOS-style \r\n characters | The modes "wb" or "rb" are used the vast majority of the time. |
ReturnsFile pointer, or zero if the file could not be opened.
NotesA file should be closed during the same interpreter cycle in which it is opened, or some other measure should be taken, so that a game is not saved while a file is still open. (AGAST currently makes no attempt to track open files.)
function FileClose (File)
Closes a file.
Parameters
function FileSeek (File, Position)
Seeks a position in a file.
Parameters
File | | File pointer. | Position | | Offset from the beginning of the file, in bytes. |
ReturnsTrue if successful, false if not.
function FileTell (File)
Tells the current position in a file.
Parameters
ReturnsOffset from the beginning of the file, in bytes.
function FileSize (File)
Tells the size of a file.
Parameters
ReturnsSize of the file (i.e., the offset of the last byte in the file, plus 1).
function FileReadInt (File)
Reads an integer from a file (binary, 4-bytes).
Parameters
ReturnsInteger value.
function FileWriteInt (File, IntValue)
Writes an integer to a file (binary, 4-bytes).
Parameters
File | | File pointer. | IntValue | | Integer value to write. |
function FileReadChar (File)
Reads a character from a file (text/binary, 1-byte).
Parameters
ReturnsCharacter value.
function FileWriteChar (File, CharValue)
Writes an character to a file (text/binary, 1-byte).
Parameters
File | | File pointer. | CharValue | | Character to write. |
function FileWriteString (File, String)
Writes a string to a file (text/binary, 1-byte per character). No type of delimiter is written, but you can do that using FileWriteChar, if desired.
Parameters
File | | File pointer. | String | | String index. |
function FileReadString (File, String, Delimiter, MaxSize)
Reads a string from a file until the delimiter is read, the end of the file is reached, or the maximum size is read. The delimiter is used as a marker, and does not become part of the string is read.
Parameters
File | | File pointer. | String | | String index. | Delimiter | | Delimiter. This is an ASCII character value, and not a string value. | MaxSize | | Maximum size to read. Do not make this number outrageously huge, because a temporary buffer of this size will be allocated for loading. |
ReturnsReturns 'true' if the delimiter was encountered, or 'false' if the string was terminated by some other condition. (You can use the StringLength function afterwards to determine the number of characters read.)
|
