Home Contents | # Line buffering | Rawio | Core4 Lua Event System

## SYNOPSIS

1. flag = handle:canReadLine()
2. line = handle:line()
3. for line in handle:lines() do ...

## DESCRIPTION

This is a set of functions that deal with line buffered input. A line may be terminated by NL (Code 10, Unix method), CRNL (Codes 13 & 10, Windows method) or CR (Code 13, old-style MacOS method).

The function rawio:canReadLine() tests if a full line of data can be read from the handle or if any other exceptional condition exists. The idea is to return true if it is useful to call one of the other two functions.

One line of data is read by calling rawio:line().

Using the iterator rawio:lines(), a loop will run as long as there are full lines available from the file handle.

In blocking mode, all functions will wait for data to arrive if no full line can be read.

## RETURN VALUE

rawio:canReadLine() returns true if an interesting condition exists on the file handle: A line can be read, end-of-file or an error has occured.

On success, rawio:line() returns a string containing the line, with the line terminator stripped away. On failure or end-of-file, returns nil. In case of an error, the error can be retrieved using rawio:lastError().

rawio:lines() returns a standard for-loop iterator.

## BUGS

As a side effect, the function rawio:canReadLine() might read all data from kernel into a buffer. This prevents a POLLIN event listener from triggering unless more data arrives. To avoid lockups, code using rawio:canReadLine() in combination with POLLIN events must always loop until no more lines can be read from the handle.

## EXAMPLE

> > > > > > >
handle = rawio.attach(0) for line in handle:lines() do print(string.format("LINE: \"%s\"", line)) end Hello World Test
LINE: "Hello World" LINE: "" LINE: "Test"

## SEE ALSO

rawio.attach, rawio:blocking, rawio:clearError, rawio:close, rawio:connect, rawio:detach, rawio:lastError, rawio.access, rawio.open, rawio:read, rawio:slurp, rawio:copy, rawio.stat, rawio.statfs, rawio:writet, rawio:writes, rawio:write