This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
api:buffer [2016/06/18 20:50] payonel [Instance Methods] |
api:buffer [2016/06/19 07:56] (current) payonel [Instance Methods] |
||
|---|---|---|---|
| Line 47: | Line 47: | ||
| - `b:lines([line_formats...]) string array` | - `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. | + | Returns a function iterator which reads from the stream until it reaches nil. On each read, the `line_formats` list of args as 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. |
| ```lua | ```lua | ||
| Line 62: | Line 62: | ||
| | | ||
| 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: | 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: | ||
| - | ``` | + | |
| - | local file = io.open( | + | * a number value, e.g. `10` |
| - | ``` | + | |
| - | * a number value, e.g. `b:read(10)` | + | Read **n** bytes (in binary mode) or chars (in text mode) from the stream; result is returned as a string. See [[api:non-standard-lua-libs#input_and_output_facilities|io.open]] for more details about how to open files in different modes. |
| - | Read **n** bytes from the stream, result is a string | + | |
| - | + | `local chars = b:read(10)` | |
| - | * "\*n", "\*number" | + | |
| - | Read the next series of bytes from the stream and that can be interpreted as a number | + | * "\*n" or "\*number" |
| - | + | ||
| - | * "\*l", "\*line" | + | Read the next series of bytes from the stream that can be interpreted as a number. Note that reading numbers is also affected by the open mode, binary or text. See [[api:non-standard-lua-libs#input_and_output_facilities|io.open]] for more details about how to open files in different modes.. |
| - | Read the next line from the stream, chopping off the line ending marker (which may be \n, \r, or \r\n) | + | |
| - | + | `local number = b:read("*n")` | |
| - | * "\*L", "\*Line" | + | |
| - | Read the next line from the stream, like "*line", but preserves the line ending marker as part of the result | + | * "\*l" or "\*line" |
| - | + | ||
| - | * "\*a", "\*all" | + | Read the next line from the stream, chopping off the line ending marker (which may be \n, \r, or \r\n) |
| - | Reads all remaining data from the stream until nil. There would be no point in having formats following this. | + | |
| + | `local line = b:read("*l")` | ||
| + | |||
| + | * "\*L" or "\*Line" | ||
| + | |||
| + | Read the next line from the stream, like "*line", but preserves the line ending marker as part of the result | ||
| + | |||
| + | `local whole_line = b:read("*L")` | ||
| + | |||
| + | * "\*a" or "\*all" | ||
| + | |||
| + | Reads all remaining data from the stream until nil. There would be no point in having formats following this. | ||
| + | |||
| + | `local the_whole_file = b:read("*a")` | ||
| - `b:getTimeout() number` | - `b:getTimeout() number` | ||
| Line 89: | Line 102: | ||
| ```lua | ```lua | ||
| - | local file = buffer.new("r", { read = function() os.sleep(5) return "abc" end }) | + | local file = buffer.new("r", { read = function() os.sleep(5) return "a" end }) |
| file:setvbuf("full", 1) -- set buffer size to 1 char | file:setvbuf("full", 1) -- set buffer size to 1 char | ||
| file:setTimeout(1) -- set buffer timeout to 1 second | file:setTimeout(1) -- set buffer timeout to 1 second | ||
| Line 96: | Line 109: | ||
| ``` | ``` | ||
| - | - `b:seek` | + | - `b:seek([whence:string], [offset:number])` |
| + | |||
| + | Moves the stream position by `offset` bytes from `whence`, both optional params. `whence` defaults to "cur", and `offset` defaults to 0. | ||
| + | Valid `whence` values: | ||
| + | - "cur" from the current position. | ||
| + | - "set" from the start of the stream. | ||
| + | - "end" from the end of the stream. | ||
| + | Returns the result of the seek operation on the stream (which may fail). | ||
| - | about seek | ||
| Interface Methods | Interface Methods | ||
| ----------- | ----------- | ||
| + | |||
| The following methods are expected to be implemented on the buffered streams passed to `buffer.new`. | The following methods are expected to be implemented on the buffered streams passed to `buffer.new`. | ||
| - | close | + | - `close() ok, reason` |
| - | write | + | |
| - | read | + | Close handles, release resources, disconnect -- and return success |
| - | seek | + | |
| + | - `write(arg: string) ok, reason` | ||
| + | |||
| + | Write `arg` as bytes, assume a string of plain unformatted chars. Return falsey and reason on failure. | ||
| + | |||
| + | - `read(n: number) ok, reason` | ||
| + | |||
| + | Return `n` bytes, and **not** `n` unicode-aware chars. Assume your data is binary data and let the buffer library manage the mode and the unicode string packaging (if applicable). Note that this is exactly how the [[api:filesystem|filesystem]] library operates.The caller assumes there is more data to read until `nil` is returned. A empty string or a string shorter than `n` chars long is a valid return, but the caller may assume there is more data to request until `nil` is returned. | ||
| + | |||
| + | - `seek([whence: string], [offset: number]) [offset from start] or falsey, reason` | ||
| + | |||
| + | Refer to `b:seek()` for details. In short, move the stream position to `offset` from `whence`, and return the `offset` from the start of the stream of the position after the seek operation. Note that `seek("cur", 0)` is a valid request, typical of the caller wanting to determine the current position of the stream. Your stream is not required to support `seek`, in such case (or in any case of failure) you should return nil, and the reason (as a string) for the failure. | ||