From e084e2ca33537d378ca008fd13bb7d989f7d22d9 Mon Sep 17 00:00:00 2001
From: Philipp Janda <siffiejoe@gmx.net>
Date: Fri, 23 Jan 2015 00:13:16 +0100
Subject: document LUA_KFUNCTION macro, update readme

---
 README.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9a01583..303758e 100644
--- a/README.md
+++ b/README.md
@@ -142,6 +142,8 @@ For Lua 5.1 additionally:
 
 * bit operators
 * integer division operator
+* utf8 escape sequences
+* 64 bit integers
 * `coroutine.isyieldable`
 * Lua 5.1: `_ENV`, `goto`, labels, ephemeron tables, etc. See
   [`lua-compat-5.2`][2] for a detailed list.
@@ -149,7 +151,7 @@ For Lua 5.1 additionally:
   * `lua_isyieldable`
   * `lua_getextraspace`
   * `lua_arith` (new operators missing)
-  * `lua_pushfstring` (new formats missing)
+  * `lua_push(v)fstring` (new formats missing)
   * `lua_upvalueid` (5.1)
   * `lua_upvaluejoin` (5.1)
   * `lua_version` (5.1)
@@ -158,6 +160,41 @@ For Lua 5.1 additionally:
   * `luaL_loadbufferx` (5.1)
   * `luaL_loadfilex` (5.1)
 
+### Yieldable C functions
+
+The emulation of `lua_(p)callk` for previous Lua versions is not 100%
+perfect, because the continuation functions in Lua 5.2 have different
+signatures than the ones in Lua 5.3 (and Lua 5.1 doesn't have
+continuation functions at all). But with the help of a small macro the
+same code can be used for all three Lua versions (the 5.1 version
+won't support yielding though).
+
+Original Lua 5.3 code (example adapted from the Lua 5.3 manual):
+
+```C
+static int k (lua_State *L, int status, lua_KContext ctx) {
+  ...  /* code 2 */
+}
+
+int original_function (lua_State *L) {
+  ...     /* code 1 */
+  return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
+}
+```
+
+Portable version:
+
+```C
+LUA_KFUNCTION( k ) {
+  ...  /* code 2; parameters L, status, and ctx available here */
+}
+
+int original_function (lua_State *L) {
+  ...     /* code 1 */
+  return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
+}
+```
+
 ## See also
 
 * For Lua-5.2-style APIs under Lua 5.1, see [lua-compat-5.2][2],
-- 
cgit v1.2.3-55-g6feb