_{Official ZPE/YASS documentation}TextFileReader

Introduction

The TextFileReader object provides a simple way to read a UTF-8 text file line-by-line without loading the whole file into memory.

In ZPE 1.14.9, the object was renamed from SequentialFile to TextFileReader. The old name was not retained as an alias. The implementation was also improved and several new functions were added. The old get_current function was replaced by the more clearly named peek_line function.

The reader stores the next available line internally. Calling read_line returns that line and advances the reader, while peek_line returns it without advancing. The underlying file is closed automatically when the end of the file is reached, although it can also be closed explicitly.

A file can be supplied to the constructor or opened later using open. Both operations require permission level 4. All other functions require permission level 0.

TextFileReader object functions

The following is a list of the native functions exposed by the TextFileReader object.

TextFileReader(string file) ⇒ TextFileReader

Creates a TextFileReader and opens file for reading.

open(string file) ⇒ boolean

Closes any previously opened file, then opens file for sequential reading. Returns true when the file was opened successfully, or false when it could not be opened.

has_next() ⇒ boolean

Returns true when another line is available.

read_line() ⇒ string | undefined

Returns the next line and advances the reader. Returns undefined when no line is available.

peek_line() ⇒ string | undefined

Returns the next line without advancing the reader. Returns undefined when no line is available.

close() ⇒ boolean

Closes the file. Returns true when it was closed successfully.

is_open() ⇒ boolean

Returns true while the underlying file reader is open.

line_number() ⇒ number

Returns the number of lines read from the current file. The first successful call to read_line changes this value from 0 to 1.

file() ⇒ string

Returns the name of the current or most recently opened file.

Examples

Reading a file line-by-line:

$f = new TextFileReader("data.txt")

while ($f->has_next())
    print($f->read_line())
end

Opening a file separately and peeking at the next line:

$f = new TextFileReader()

if ($f->open("data.txt"))
    while ($f->has_next())
        $peek = $f->peek_line()
        print("Next: " & $peek)
        $line = $f->read_line()
    end

    print("Lines read: " & $f->line_number())
    $f->close()
else
    print("Failed to open file.")
end

Notes:

• Encoding: Files are read as UTF-8 text.
• Permissions: The constructor and open require permission level 4 because they access the file system.
• End of file: At the end of the file, has_next returns false and read_line and peek_line return undefined.
• Automatic closing: The underlying reader is closed automatically after the final line has been consumed.