The buffer
library provides user friendly streams. These are the kind that the io
library returns from io.open
unlike the raw streams returned by filesystem.open
which don't support as many helpful methods. These helper methods on the file handles you get from io.open
are defined here, under Instance Methods. Thus, this API documentation is important and helpful even if you aren't building your own buffered streams.
Additionally, this API allows you to create buffered streams. You provide the backend stream read and write, the buffer library provides the formatting and buffering of the data. Generally, users will not need to make their own buffered streams. For reference, the io library uses buffered streams (which includes file io as well as terminal io)
The following methods are called on the buffer
library itself.
buffer.new([mode: string], stream: table)
Creates a new buffered stream, wrapping stream
with read-write mode
. mode
can be readonly (r or nil
), read-write (rw), or write-only (w). Read about the stream interface methods required on the stream
object.
The following methods can only be called on instances created by buffer.new
(note file handles returned by io.open
are also buffered streams, created with buffer.new
). These methods are instance methods, requiring instance call notation :
. In order to help differentiate these instance methods from static methods (e.g. buffer.new
), b:
will be used to prefix the method names.
b:flush()
If any data is buffered it is immediately written to the stream and released.
b:close()
Flushes the buffer and closes the wrapped stream.
b:setvbuf([mode: string], [size: number]) mode, size
Sets the buffering mode
and size
and returns the result mode
and size
. The amount of data buffered is specified by size
which defaults to [512, 8192] bytes, depending on available system memory. mode
and size
can be nil, in which case the previous values are used for either. size
is also used in read(n)
calls to the stream.
Modes only affect write
, which include:
size
bytes. This is the default mode.size
is reached, whichever comes first.
b:write([values...])
Writes each value
to the stream, first buffering based on the mode and buffer size (see setvbuf
)
local file = io.open("/tmp/foo.txt") file:write("abc", "def", "\n") file:close() -- foo.txt now has "abcdef\n"
b:lines([line_formats...]) string array
Returns a function iterator which reads from the stream until it reaches nil. On each read, the line_formats
list of args ais passed to stream:read(...)
. The overwhelmingly typical use is to not define line_formats
, i.e. passing no args to lines()
. The default behavior (i..e without line_formats
) is to read a “line” at a time from the stream.
local file = io.open("/tmp/foobar.txt") for line in file:lines() do process_next_line(line) end file:close()
b:read([formats...]) string...
A fairly advanced reader that support various formats. First of all, if called with no format
, i.e an empty param list, it reads the next line from the stream, which is equivalent to read("*l")
Each format
is read from the stream and all returned in a multiple return value list of the results. Note all format strings are prefixed with * and also note that only the first char of the string names of the formats matters, the rest is ignored. These are the supported formats:
b:read(10)
Read n bytes from the stream, result is a string
Read the next series of bytes from the stream and that can be interpreted as a number
Read the next line from the stream, chopping off the line ending marker (which may be \n, \r, or \r\n)
Read the next line from the stream, like “*line”, but preserves the line ending marker as part of the result
Reads all remaining data from the stream until nil. There would be no point in having formats following this.
b:getTimeout
about getTimeout
b:setTimeout
about setTimeout
b:seek
about seek
The following methods are expected to be implemented on the buffered streams passed to buffer.new
.
close write read seek