diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.mdwn | 9 | ||||
| -rw-r--r-- | doc/index.mdwn | 13 | ||||
| -rw-r--r-- | doc/modules/luaevent.core.buffer.mdwn | 61 | ||||
| -rw-r--r-- | doc/modules/luaevent.core.bufferevent.mdwn | 0 | ||||
| -rw-r--r-- | doc/modules/luaevent.core.mdwn | 0 | ||||
| -rw-r--r-- | doc/modules/luaevent.mdwn | 0 |
6 files changed, 83 insertions, 0 deletions
diff --git a/doc/api.mdwn b/doc/api.mdwn new file mode 100644 index 0000000..aa528d4 --- /dev/null +++ b/doc/api.mdwn @@ -0,0 +1,9 @@ +LuaEvent API Documentation +---- + +Modules: + +* [[modules/luaevent.core]] - Interface to core libevent functions + * [[modules/luaevent.core.buffer]] - Interface to libevent's evbuffer + * [[modules/luaevent.core.bufferevent]] - Interface to libevent's bufferevent +* [[modules/luaevent]] - Higher level wrapper mimicking [copas](http://www.luaforge.net/projects/copas) diff --git a/doc/index.mdwn b/doc/index.mdwn new file mode 100644 index 0000000..7b1d8d3 --- /dev/null +++ b/doc/index.mdwn @@ -0,0 +1,13 @@ +LuaEvent is a Lua wrapper around [libevent](http://monkey.org/~provos/libevent/). +It provides an interface with which you can write applications that wait on +file-descriptor events (primarily socket-based). + +[[API_Reference|api]] + +---- +Related links for this project: + +* LuaForge @ <http://luaforge.net/projects/luaevent/> +* GitRepo @ <http://repo.or.cz/w/luaevent.git/> +* ohloh @ <http://www.ohloh.net/projects/8077/> + diff --git a/doc/modules/luaevent.core.buffer.mdwn b/doc/modules/luaevent.core.buffer.mdwn new file mode 100644 index 0000000..4b2eac4 --- /dev/null +++ b/doc/modules/luaevent.core.buffer.mdwn @@ -0,0 +1,61 @@ +---- +Functions: + +[[toc levels=1]] + +## buffer.new +* Instantiates a new buffer object + +## buffer:add +* Successively concatenates each of the arguments onto the buffer +* Input: `(...)` + * Sequence of strings or buffer instances +* Side Effects: Buffers 'add'ed are emptied of their contents (per libevent semantics) +* Output: Amount of data added +(QUESTION: Should add return the buffer itself so that chaining can be easy) + +## buffer:length (`__len`) +* Output: Length of the remaining buffer contents + +## buffer:get\_data (`__tostring`) +* Input: + * `()` and `__tostring` - Returns all data in the buffer + * `(len)` - Returns data up to `len` bytes long + * `(begin, len)` - Returns data beginning at `begin` up to `len` bytes long + * If `begin < 0`, wraps at data length. Ex: (-1, 1) returns last byte, (-2, 2) returns last 2 bytes +* Output: A copy of contents from the buffer + +## buffer:read +* Reads data from a file-descriptor/socket into the buffer directly +* Input: `(integer/lightuserdata fd OR socket, length)` + * `fd` - File descriptor as integer or lightuserdata 'handle' (cast to a native integer) + * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle + * `length` - Amount of data to attempt to read into the buffer +* Output: Length of data actually read into the buffer +* Side Effects: fd/socket 'drain'ed of data + +## buffer:write +* Attempts to write out all buffer's data to a file-descriptor/socket +* Input: `(integer/lightuserdata fd OR socket, length)` + * `fd` - File descriptor as integer or lightuserdata 'handle' (cast to a native integer) + * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle +* Output: Amount of data written +* Side Effects: buffer 'drain'ed of written data + +## buffer:readline +* Reads a line terminated by either '\r\n', '\n\r', '\r', or, '\n' +* Output: + * If no terminator found: nil + * If terminator found: Line returned without terminators +* NOTE: If a '\r' or '\n' are the last characters in the buffer, then the data is returned even if the +potential later data would contain the paired '\n' or '\r'. (TODO: Ask libevent list on how this is handled...) + +## buffer:drain +* Removes data from the buffer +* Input: `(amt)` + * If `amt < 0` drains all data due to auto-casting to unsigned int and capping... + TODO: Add code to check this condition explicitly for safety + * If `amt >= 0`, drain up to amt from the buffer (no problem w/ too-large values) + +## buffer:close (`__gc`) +* Immediately frees/closes a buffer. Note that diff --git a/doc/modules/luaevent.core.bufferevent.mdwn b/doc/modules/luaevent.core.bufferevent.mdwn new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/modules/luaevent.core.bufferevent.mdwn diff --git a/doc/modules/luaevent.core.mdwn b/doc/modules/luaevent.core.mdwn new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/modules/luaevent.core.mdwn diff --git a/doc/modules/luaevent.mdwn b/doc/modules/luaevent.mdwn new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/modules/luaevent.mdwn |