From 53e9937082895ba141a25281f67bddf52644125c Mon Sep 17 00:00:00 2001
From: Aleteoryx <alyx@aleteoryx.me>
Date: Mon, 2 Sep 2024 22:35:46 -0400
Subject: [PATCH] readme engo

---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 75 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ceb4032..712ee95 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,77 @@
 # nex.nelua
 
-nightfall express and nightfall postal service servers written in the
-[nelua](https://nelua.io) programming language
+[nightfall express](https://nightfall.city/nex/info/specification.txt)
+and [nightfall postal service](https://nightfall.city/nps/info/specification.txt)
+servers written in the [nelua](https://nelua.io) programming language.
+
+these aren't intended as full servers, they serve entirely from code.
+you'll need to write up your backend yourself, but it's more fun that
+way.
+
+this implementation relies on the `epoll` family of syscalls, so YMMV
+on non-linux or non-freebsd systems.
+
+## building
+
+install the nelua compiler, clone the repo. `nex.nelua` and `nps.nelua`
+are the 2 base scripts to play with. their implementations are
+barebones but should serve as a good starting point.
+
+once you're happy with your setup, make them into binaries with
+
+    nelua -r -o nex nex.nelua
+    nelua -r -o nps nps.nelua
+
+and throw them up somewhere
+
+## socket.nelua
+
+a pretty minimal asynchronous socket library. it should have a
+familiar-if-limited interface to anyone who has used a higher-level
+asynchronous API. it is sufficient to implement most text-mode network
+protocols, so long as they are not reliant on multiple sockets.
+
+it exposes the following methods from its return value:
+
+### `socket.listen_tcp(addr: string, handler: function(): void)`
+
+listens on the host/port in `addr`. panics if it can't connect or if
+`addr` is malformed. `addr` is either of the format `IPV4:PORT` or
+`{IPV6}:PORT`. passes the connection to `socket.listen_sock`.
+
+### `socket.listen_sock(fd: cint, handler: function(): void)`
+
+`fd` must be a valid socket, bound to some address and ready to
+`accept` incoming connections. as connections are made, `handler` will
+be executed in the context of a coroutine. it is expected to call one
+of the provided [yielding functions](#yielding-functions) eventually.
+
+if there is any error reading from or writing to the socket, the
+handler coroutine is deleted and the connection is dropped.
+
+it is unwise to `coroutine.yield` manually from the context of a
+handler function.
+
+### yielding functions
+
+functions provided for handlers to interact with their associated
+socket
+
+#### `socket.send(data: string)`
+
+writes `data` over the network
+
+#### `socket.send_line(data: string)`
+
+writes `data` over the network with newline appended
+
+#### `socket.recv_line(): string`
+
+waits for an incoming line of text. returns it with newline stripped
+
+this function is not CRLF-aware, and you make need to strip those
+manually.
+
+#### `socket.end_conn()`
+
+closes the connection and deletes this coroutine
-- 
2.43.4