[edit] vx.File
A file handle, which can either read from or write to the disk.
[edit] Constructors
vx.File(filename, mode)
- Opens a file, with a mode specified by the vx.FileMode table. There is chance of the open failing.
- You should always check the opened attribute before continuing with the rest of your file manipulations.
[edit] Attributes
vx.File.opened -> boolean (readonly)
- Whether the file handle was successfully opened. If it fails, that could mean a file doesn't exist, or a save location is write-protected.
- Important: Check this before continuing with the rest of your file manipulations.
vx.File.eof -> boolean (readonly)
- Whether the file handle has read to the end of the file, which only really has meaning when opened with
vx.FileMode.Read.
[edit] Methods
vx.File:Close()
- Destroys the file handle. Any further file operation on this object will probably not end so pretty.
- Please! Close any files you open when you're done with them. Files opened in write mode might not have their data stored on disk unless you remember to close them when you're done.
vx.File:ReadByte() -> number
- Reads a single byte (an unsigned 8-bit binary integer) from the file.
vx.File:ReadWord() -> number
- Reads two bytes (an unsigned 16-bit binary integer) from the file.
vx.File:ReadQuad() -> number
- Reads four bytes (a signed 32-bit binary integer) from the file.
vx.File:ReadString() -> string
- Reads a special, Verge-formatted binary string, which is a 2-byte (word) length delimiter followed by a stream of characters.
vx.File:ReadLine() -> string
- Reads from a file until a newline or EOF occurs.
vx.File:ReadToken() -> string
- Reads all characters until any whitespace or EOF occurs. Possibly useful for grabbing entries separated by spaces/tabs/lines.
vx.File:Write(s)
- Writes a string exactly as it provided to the disk. Exactly one byte per character is written. No escape sequences or special characters are added. Good for plain-text storage.
vx.File:WriteByte(b)
- Writes a number in the range 0..255 to disk, as a single byte. If this number has a decimal part, it will be truncated when written to disk.
vx.File:WriteWord(w)
- Writes a number in the range 0..65535 to disk, as a two byte little-endian sequence. If this number has a decimal part, it will be truncated when written to disk.
vx.File:WriteQuad(q)
- Writes a number in the range -2147483648..2147483647 to disk, as a four byte little-endian sequence. If this number has a decimal part, it will be truncated when written to disk.
- TODO: The rest of this method documentation.
vx.File:WriteLine(s)
- Writes a string to disk, with a CR/LF newline sequence following it, effectively the same as typing a string and hitting enter on a Windows box.
vx.File:WriteString(s)
- Writes a special, Verge-formatted binary string, which is a 2-byte (word) length delimiter followed by a stream of characters. The 2-byte delimiter means that a string could be at max 65535 characters. I am pretty sure even this is a bit too much to save at one time. But anyways.
vx.File:Seek(position, seek_mode)
- Seek to a new position in the file. Depending on the value of
seek_mode (which is one of the values in vx.SeekMode), it will use different rules to jump within the file.
vx.File:GetPosition() -> number
- Returns the current position of the file handle, which is an offset in bytes since the start of the file.
vx.File:SeekLine(line)
- Seeks to a specific line within the file, with the numbers starting from 0 for the first line, 1 for the second line, and so on.
After opening any file, check vx.File.opened whether it was opened successfully before continuing. Always remember to call vx.File:Close when you're done with it.