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