aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/api.mdwn9
-rw-r--r--doc/index.mdwn13
-rw-r--r--doc/modules/luaevent.core.buffer.mdwn61
-rw-r--r--doc/modules/luaevent.core.bufferevent.mdwn0
-rw-r--r--doc/modules/luaevent.core.mdwn0
-rw-r--r--doc/modules/luaevent.mdwn0
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