| 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: `(fd, length)` |
| 31 | * `fd` - File descriptor to read from |
| 32 | * `length` - Amount of data to attempt to read into the buffer |
| 33 | * Output: Length of data actually read into the buffer |
| 34 | * Side Effects: fd/socket 'drain'ed of data |
| 35 | |
| 36 | ## buffer:write |
| 37 | * Attempts to write out all buffer's data to a file-descriptor/socket |
| 38 | * Input: `(fd, length)` |
| 39 | * `fd` - File descriptor to write to |
| 40 | * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle |
| 41 | * Output: Amount of data written |
| 42 | * Side Effects: buffer 'drain'ed of written data |
| 43 | |
| 44 | ## buffer:readline |
| 45 | * Reads a line terminated by either '\r\n', '\n\r', '\r', or, '\n' |
| 46 | * Output: |
| 47 | * If no terminator found: nil |
| 48 | * If terminator found: Line returned without terminators |
| 49 | * NOTE: If a '\r' or '\n' are the last characters in the buffer, then the data is returned even if the |
| 50 | potential later data would contain the paired '\n' or '\r'. (TODO: Ask libevent list on how this is handled...) |
| 51 | |
| 52 | ## buffer:drain |
| 53 | * Removes data from the buffer |
| 54 | * Input: `(amt)` |
| 55 | * If `amt < 0` drains all data due to auto-casting to unsigned int and capping... |
| 56 | TODO: Add code to check this condition explicitly for safety |
| 57 | * If `amt >= 0`, drain up to amt from the buffer (no problem w/ too-large values) |
| 58 | |
| 59 | ## buffer:close (__gc) |
| 60 | * Immediately frees/closes a buffer. Note that |