class File extends Object
Provides an interface for file input/output, such as reading or writing text or retrieving its length. FileOpen returns an object of this type.
Calling the class itself opens a File over a Buffer.
"FileObj" is used below as a placeholder for any File object, as "File" is the class itself.
In addition to the methods and properties inherited from Object, File objects have the following predefined methods and properties.
Calling the File class returns a File whose contents are memory the script already holds.
FileObj := File(Source , Encoding)
A Buffer-like object whose memory becomes the file's contents.
Type: String
If omitted, UTF-8 is used. Otherwise, an encoding name as accepted by FileEncoding, applied to the text methods.
A write past the end of Source throws an Error. The File keeps Source alive for as long as the File exists.
Handle is 0.
To open a path, use FileOpen. Calling File() with no source throws a ValueError.
Builds a binary record in a Buffer, then reads it back field by field.
buf := Buffer(16, 0) f := File(buf) f.WriteUInt(0xDEADBEEF) f.WriteInt64(-42) f.WriteShort(1234) f.Seek(0) MsgBox f.ReadUInt() " " f.ReadInt64() " " f.ReadShort() ; 3735928559 -42 1234 MsgBox NumGet(buf, 0, "UInt") ; 3735928559 - the bytes are in the Buffer itself
Reads a string of characters from the file and advances the file pointer.
String := FileObj.Read(Characters)
Type: Integer
If omitted, the rest of the file is read and returned as one string. Otherwise, specify the maximum number of characters to read. If the File object was created from a handle to a non-seeking device such as a console buffer or pipe, omitting this parameter may cause the method to fail or return only what data is currently available.
With UTF-8, a surrogate pair which does not fit is left for the next read; Read(1) at such a character returns the whole pair. UTF-16 reads count code units.
Stateful code pages return complete decoding groups. The first group of a read is returned intact even if it exceeds the requested character count. This preserves its characters and keeps unread bytes available to raw reads.
Unfinished multibyte characters stay at the current byte position, so a later RawRead reads their bytes.
Type: String
This method returns the string of characters that were read.
Writes a string of characters to the file and advances the file pointer.
BytesWritten := FileObj.Write(String)
Type: String
The string to write.
Type: Integer
This method returns the number of bytes (not characters) that were written.
Reads a line of text from the file and advances the file pointer.
TextLine := FileObj.ReadLine()
Type: String
This method returns a line of text, excluding the line ending.
A line of any length is read whole. At the end of the file, an empty string is returned.
As in AutoHotkey, CR and LF are recognized in the encoded bytes before text is decoded. A code page's escape or shift sequences do not change how line endings are recognized.
Writes a line of text to the file and advances the file pointer.
BytesWritten := FileObj.WriteLine(String)
Type: String
If blank or omitted, an empty line will be written. Otherwise, specify the string to write, which is always followed by `n or `r`n, depending on the EOL flags used to open the file.
Type: Integer
This method returns the number of bytes (not characters) that were written.
Reads a number from the file and advances the file pointer.
Num := FileObj.ReadNumType()
NumType is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with DllCall.
Type: Integer, Float or String (empty)
On success, this method returns a number. On failure, it returns an empty string.
If the number of bytes read is non-zero but less than the size of NumType, the missing bytes are assumed to be zero.
Writes a number to the file and advances the file pointer.
BytesWritten := FileObj.WriteNumType(Num)
NumType is either UInt, Int, Int64, Short, UShort, Char, UChar, Double, or Float. These type names have the same meanings as with DllCall.
Type: Integer
This method returns the number of bytes that were written. For example, FileObj.WriteUInt(42) returns 4 if successful.
Reads raw binary data from the file into memory and advances the file pointer.
BytesRead := FileObj.RawRead(Buffer , Bytes)
The Buffer-like object or memory address which will receive the data.
Reading into a Buffer is recommended. If Bytes is omitted, it defaults to the size of the buffer. An exception is thrown if Bytes exceeds the size of the buffer.
If a memory address is passed, Bytes must also be specified.
Type: Integer
The maximum number of bytes to read. This is optional when Buffer is an object; otherwise, it is required.
Type: Integer
This method returns the number of bytes that were read.
Writes raw binary data to the file and advances the file pointer.
BytesWritten := FileObj.RawWrite(Data , Bytes)
Type: Object, String or Integer
A Buffer-like object or string containing binary data, or a memory address. If an object or string is specified, Bytes is optional and defaults to the size of the buffer or string. Otherwise, Bytes must also be specified.
Type: Integer
The number of bytes to write. This is optional when Data is an object or string; otherwise, it is required.
Type: Integer
This method returns the number of bytes that were written.
Moves the file pointer.
IsMoved := FileObj.Seek(Distance , Origin)
Type: Integer
Distance to move, in bytes. Lower values are closer to the beginning of the file.
Type: Integer
If omitted, it defaults to 2 when Distance is negative and 0 otherwise. Otherwise, specify one of the following numbers to indicate the starting point for the file pointer move:
Type: Integer (boolean)
On success, this method returns 1 (true). On failure, it returns 0 (false).
This method is equivalent to FileObj.Pos := Distance, if Distance is not negative and Origin is omitted or 0 (SEEK_SET).
Writes buffered data to the underlying file or stream without closing it.
FileObj.Flush()
Closes the file, flushes any data in the cache to disk and releases the share locks.
FileObj.Close()
Although the file is closed automatically when the object is freed, it is recommended to close the file as soon as possible.
Gets or sets the position of the file pointer.
CurrentPos := FileObj.Pos
FileObj.Pos := NewPos
CurrentPos and NewPos are a byte offset from the beginning of the file, where 0 is the first byte. When data is written to or read from the file, the file pointer automatically moves to the next byte after that data.
This property is equivalent to FileObj.Seek(NewPos).
Gets or sets the size of the file.
CurrentSize := FileObj.Length
FileObj.Length := NewSize
CurrentSize and NewSize are the size of the file, in bytes.
This property should be used only with an actual file. If the File object was created from a handle to a pipe, it may return the amount of data currently available in the pipe's internal buffer, but this behaviour is not guaranteed.
Gets a non-zero number if the file pointer has reached the end of the file, otherwise zero.
IsAtEOF := FileObj.AtEOF
A closed file reports a non-zero value. For a non-seeking stream such as a pipe, this property reports whether the read-ahead buffer is empty without probing the device; it cannot determine whether more input will arrive.
Gets or sets the text encoding used by this file object.
CurrentEncoding := FileObj.Encoding
FileObj.Encoding := NewEncoding
NewEncoding may be a numeric code page identifier (see Microsoft Docs) or one of the following strings.
CurrentEncoding is one of the following strings:
UTF-8: Unicode UTF-8, equivalent to CP65001.UTF-16: Unicode UTF-16 with little endian byte order, equivalent to CP1200.CPnnn: a code page with numeric identifier nnn.CurrentEncoding is never a value with the -RAW suffix, regardless of how the file was opened or whether it contains a byte order mark (BOM). Setting NewEncoding never causes a BOM to be added or removed, as the BOM is normally written to the file when it is first created.
Setting NewEncoding to UTF-8-RAW or UTF-16-RAW is valid, but the -RAW suffix is ignored. This only applies to FileObj.Encoding, not FileOpen.
Gets a system file handle, intended for use with DllCall. See CreateFile.
Handle := FileObj.Handle
File objects internally buffer reads or writes. If data has been written into the object's internal buffer, it is committed to disk before the handle is returned. If the buffer contains data read from file, it is discarded and the actual file pointer is reset to the logical position indicated by the Pos property.