This is lua-termkey, lua bindings to LeoNerd's libtermkey. This was
written against libtermkey-0.22.

Libtermkey may be found at http://www.leonerd.org.uk/code/libtermkey

You're probably reading this wanting to know how to translate between
termkey.h and these bindings. So, assume you have written

        local termkey = require("termkey")

Now, here's what you just imported.

 - tk = termkey.new(t)

   Returns tk, a garbage-collected TermKey* object (the garbage
   collection calls termkey_destroy, not termkey_free), or nil on error.
   t should be a table, where the following keys have meaning (all the
   booleans default to false).

    - t["fd"] integer; the file descriptor to attach to tk. Defaults to 1.

    - t["nointerpret"] boolean; true means "Do not interpret C0//DEL codes if possible"

    - t["convertkp"] boolean; true means "Convert KP codes to regular keypresses"

    - t["raw"] boolean; true means "Input is raw bytes, not UTF-8"

    - t["utf8"] boolean; true means "Input is definitely UTF-8"

    - t["notermios"] boolean; true means "Do not make initial termios calls on construction"

    - t["spacesymbol"] boolean; true means "Sets TERMKEY_CANON_SPACESYMBOL"

    - t["ctrlc"] boolean; true means "Allow Ctrl-C to be read as normal, disabling SIGINT"

    - t["eintr"] boolean; true means "Return ERROR on signal (EINTR) rather than retry"

    - t["nostart"] boolean; true means "Do not call termkey_start() in constructor"

      Note: At the time of writing, with termkey 0.22, the following program

          termkey=require('termkey')
          tk=termkey.new({ nostart = true })
          -- implicit end of program, and garbage collection of tk

      is equivalent to

          #include <termkey.h>
          int main(void)
          {
              TermKey *tk = termkey_new(1, TERMKEY_FLAG_NOSTART);
              termkey_destroy(tk);

              return 0;
          }

      which crashes (on my machine and with my $TERM, at least). I'm not
      going to put in convoluted workarounds for this -- wrapper
      libraries aren't the place for patches.

 - tk:start() calls termkey_start(tk)

 - tk:stop() calls termkey_stop(tk)

 - tk:is_started() returns termkey_is_started(tk) as a boolean

 - tk:get_fd() returns termkey_get_fd(tk) as an integer

 - tk:get_flags() calls termkey_get_flags(tk), then returns it as a
   table such as

     { "nointerpret" = false, "convertkp" = true, ... }

   as described for termkey.new()

 - tk:get_waittime() returns termkey_get_waittime(tk) as an integer

 - tk:set_waittime(n) calls termkey_set_waittime(tk, n)

 - tk:get_canonflags() returns something like

     { spacesymbol = true, delbs = false }

   based on termkey_get_canonflags(tk)

 - tk:set_canonflags(t) calls termkey_set_canonflags(tk, flags), where
   flags is interpreted from the table, t, based on the format described
   above.

 - tk:get_buffer_size() returns termkey_get_buffer_size(tk) as an
   integer. Note that get_buffer_size returns size_t, but Lua will
   convert this into Lua_integer, which could be smaller.

 - tk:set_buffer_size(n) calls termkey_set_buffer_size(tk, n). As with
   get_buffer_size, n may be truncated during the translation.

 - tk:get_buffer_remaining() returns termkey_get_buffer_remaining(tk) as
   an integer. See get_buffer_size.

 - k = tk:getkey() calls termkey_getkey. If the result (the
   TermKeyResult) is TERMKEY_RES_NONE, k is nil. It might also be "eof",
   "again", or "error", corresponding to the appropriate return values
   of termkey_getkey.

   Finally, if termkey_getkey returned TERMKEY_RES_KEY, then k is a
   table of the following form:

     {
       codepoint = <a unicode codepoint, as an integer>
       function_number = <when F8 is pressed, this is 8>
       sym = <a string, see below>
       mouse = {
         event = <one of "unknown", "press", "drag", "release">,
         button = <integer>,
         line = <integer>,
         col = <integer>
       }
       modereport = {
         initial = <integer>,
         mode = <integer>,
         value = <integer>
       }
       position = {
         line = <integer>,
         col = <integer>
       }
       command_string = <string>
       csi = {
         args = <an array of integers>
         cmd = <integer>
       }
       -- exactly one of the above fields is present; the more complex
       -- fields are filled out according to the termkey_interpret_xyz
       -- family of functions.

       shift = <boolean>
       alt = <boolean>
       ctrl = <boolean>
       -- the above fields correspond to the modifiers field of
       -- TermKeyKey and might be omitted, implying false

       utf8 = <string>
       -- If the utf8 field of TermKeyKey contains a non-trivial string,
       -- it will be copied into this field, treated as a sequence of
       -- bytes.
     }

   The value of the sym field is obtained by taking the name of the
   value in the TermKeyKey structure (something like
   "TERMKEY_SYM_DELETE"), deleting the "TERMKEY_SYM" prefix, and
   lower-casing the result (obtaining "delete"). This includes "unknown"
   and "none". In the impossible case of TERMKEY_N_SYMS, "unknown" is
   returned.