_{Official ZPE/YASS documentation}SequentialFile

Introduction

The SequentialFileObject provides a simple way to read a text file line-by-line.

It is designed for sequential access, meaning it reads from the beginning of the file and advances one line at a time.

The typical workflow is:

• Create a new SequentialFileObject
• Open a file using open
• Use has_next to check whether more lines exist
• Read each line using read_line

Internally, the object buffers the file using a BufferedReader and always keeps the next available line stored as the “current” line.

The open function requires a permission level of 4. All other functions require permission level 0.

SequentialFile object functions

The following is a list of internal functions the SequentialFile object exposes. All functions are ZPEObjectNativeFunctions therefore run in native code.

open(string file) ⇒ boolean

Opens a file for sequential reading and loads the first line into memory. Returns true if the file was successfully opened, otherwise false.

has_next() ⇒ boolean

Returns true if there is a current line available (i.e. the end of the file has not been reached), otherwise false.

read_line() ⇒ string

Returns the current line, then advances the internal reader to the next line. When the end of the file is reached, the current line becomes null and has_next will return false.

get_current() ⇒ string

Returns the current line without advancing the file pointer. This is useful if you need to peek at the next line before consuming it.

Examples

Reading a file line-by-line:

$f = new SequentialFileObject()

if ($f->open("data.txt"))
    while ($f->has_next())
        $line = $f->read_line()
        print($line)
    end
else
    print("Failed to open file.")
end

Peeking at the next line using get_current:

$f = new SequentialFileObject()
$f->open("data.txt")

while ($f->has_next())
    # Check the line before consuming it
    $peek = $f->get_current()
    print("Next: " + $peek)

    # Now consume it
    $line = $f->read_line()
end

Notes:

• Permissions: open requires permission level 4 because it accesses the file system.
• End of file: When the end of the file is reached, has_next becomes false.
• Current line: The object always stores the “next” readable line internally as the current value.