|
1 ---- |
|
2 Functions: |
|
3 |
|
4 [[toc levels=1]] |
|
5 |
|
6 ## buffer.new |
|
7 * Instantiates a new buffer object |
|
8 |
|
9 ## buffer:add |
|
10 * Successively concatenates each of the arguments onto the buffer |
|
11 * Input: `(...)` |
|
12 * Sequence of strings or buffer instances |
|
13 * Side Effects: Buffers 'add'ed are emptied of their contents (per libevent semantics) |
|
14 * Output: Amount of data added |
|
15 (QUESTION: Should add return the buffer itself so that chaining can be easy) |
|
16 |
|
17 ## buffer:length (`__len`) |
|
18 * Output: Length of the remaining buffer contents |
|
19 |
|
20 ## buffer:get\_data (`__tostring`) |
|
21 * Input: |
|
22 * `()` and `__tostring` - Returns all data in the buffer |
|
23 * `(len)` - Returns data up to `len` bytes long |
|
24 * `(begin, len)` - Returns data beginning at `begin` up to `len` bytes long |
|
25 * If `begin < 0`, wraps at data length. Ex: (-1, 1) returns last byte, (-2, 2) returns last 2 bytes |
|
26 * Output: A copy of contents from the buffer |
|
27 |
|
28 ## buffer:read |
|
29 * Reads data from a file-descriptor/socket into the buffer directly |
|
30 * Input: `(integer/lightuserdata fd OR socket, length)` |
|
31 * `fd` - File descriptor as integer or lightuserdata 'handle' (cast to a native integer) |
|
32 * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle |
|
33 * `length` - Amount of data to attempt to read into the buffer |
|
34 * Output: Length of data actually read into the buffer |
|
35 * Side Effects: fd/socket 'drain'ed of data |
|
36 |
|
37 ## buffer:write |
|
38 * Attempts to write out all buffer's data to a file-descriptor/socket |
|
39 * Input: `(integer/lightuserdata fd OR socket, length)` |
|
40 * `fd` - File descriptor as integer or lightuserdata 'handle' (cast to a native integer) |
|
41 * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle |
|
42 * Output: Amount of data written |
|
43 * Side Effects: buffer 'drain'ed of written data |
|
44 |
|
45 ## buffer:readline |
|
46 * Reads a line terminated by either '\r\n', '\n\r', '\r', or, '\n' |
|
47 * Output: |
|
48 * If no terminator found: nil |
|
49 * If terminator found: Line returned without terminators |
|
50 * NOTE: If a '\r' or '\n' are the last characters in the buffer, then the data is returned even if the |
|
51 potential later data would contain the paired '\n' or '\r'. (TODO: Ask libevent list on how this is handled...) |
|
52 |
|
53 ## buffer:drain |
|
54 * Removes data from the buffer |
|
55 * Input: `(amt)` |
|
56 * If `amt < 0` drains all data due to auto-casting to unsigned int and capping... |
|
57 TODO: Add code to check this condition explicitly for safety |
|
58 * If `amt >= 0`, drain up to amt from the buffer (no problem w/ too-large values) |
|
59 |
|
60 ## buffer:close (`__gc`) |
|
61 * Immediately frees/closes a buffer. Note that |