Automation 4 File Stream interface This file describes the interface used for reading and writing files in Automation 4. This includes text encoding conversion routines. --- About encodings All file streams always have a text encoding. By default, this is 'utf-8', unless the file format reader/writer was registered as a text format. In that case, the default encoding will be the one set by the user before the reader or writer is invoked. All string operations on a stream follow the current encoding. You can change the encoding during reading/writing, and the change will only take effect from that point on. You can perform binary IO by setting the encoding to 'binary' and using strings consisting only of codepoints 0 to 255. --- Output File Stream user data object This object is passed to functions operating on an Output File Stream. --- Input File Stream user data object This object is passed to functions operating on an Input File Stream. --- Getting text encoding This function returns a string describing the current text encoding used for a file stream. function aegisub.fstream.get_encoding(stream) @stream (user data) The Input File Stream or Output File Stream to get the encoding for. Returns: String describing the encoding. This string can be used for setting the encoding later. --- Setting text encoding This function changes the current text encoding used for a file stream. function aegisub.fstream.set_encoding(stream, encoding) @stream (user data) The Input File Stream or Output File Stream to change the encoding for. @encoding (string) The new encoding to use. Returns: String describing the old encoding. --- File Pointer operations function aegisub.fstream.tell(stream) @stream (user data) The Input File Stream or Output File Stream get position of. Returns: Number, the number of bytes since the beginning of the file. function aegisub.fstream.seek(stream, length) @stream (user data) The Input File Stream or Output File Stream to seek in. @length (number) Number of bytes to skip. This can be negative. You can only seek backwards in an Output File Stream, and doing so truncates the file. Returns: nothing. function aegisub.fstream.reset(stream) Resets the file pointer to the start of the file. Truncates an Output File Stream to zero bytes. @stream (user data) The Input File Stream or Output File Stream to seek in. Returns: nothing. --- Reading text All these functions assume the file is in the current encoding specified. function aegisub.fstream.skip_utf_bom(stream, change_encoding) This function has undefined behaviour unless called as the first read-operation on the stream. It detects whether the file stream starts with an UTF Byte Order Mark, skips the number of bytes used by that BOM, and optionally changes the current file encoding to match the detected BOM. @stream (user data) The Input File Stream to read from. @change_encoding (boolean) If true, change encoding to match the detected BOM. Returns: Boolean, whether a BOM was detected or not. function aegisub.fstream.read(stream, length) Read a number of characters from a file. @stream (user data) The Input File Stream to read from. @length (number) Number of characters to read. If this is zero, no data are read. If this is larger than the number of characters available, data are read until the end of file. Returns: String, the string read from the file. function aegisub.fstream.read_bytes(stream, length) Read a number of bytes from a file and convert to a string. @stream (user data) The Input File Stream to read from. @length (number) The number of bytes to read. Returns: String, best-effort converted from the bytes read. function aegisub.fstream.read_line(stream, include_newline) Read until next newline in the file. A newline is defined asone of these sequences of Unicode codepoints in the decoded text: 0x0A ("\n") 0x0D ("\r") 0x0D 0x0A ("\r\n") The sequence "\n\r" is interpreted as two newlines, ie. a newline, a blank line and yet another newline. @stream (user data) The Input File Stream to read from. @include_newline (boolean) If true, include the newline character(s) in the returned string. Returns: String. --- Writing text All these functions assume the file is in the current encoding specified. function aegisub.fstream.write_utf_bom(stream) This function will corrupt your file if used anywhere else than on position 0. Write the correct UTF BOM character to the file, or nothing if not currently in an UTF encoding. @stream (user data) The Output File Stream to write the BOM to. Returns: nothing. function aegisub.fstream.write(stream, text) Write a string to a file. @stream (user data) The Output File Stream to write to. @text (string) The text to write. Returns: nothing. function aegisub.fstream.write_line(stream, text) Write a string to a file, followed by an "\r\n" newline. @stream (user data) The Output File Stream to write to. @text (string) The text to write. Returns: nothing. ---