README

   1 This is lua-termkey, lua bindings to LeoNerd's libtermkey. This was
   2 written against libtermkey-0.22.
   3
   4 Libtermkey may be found at http://www.leonerd.org.uk/code/libtermkey
   5
   6 You're probably reading this wanting to know how to translate between
   7 termkey.h and these bindings. So, assume you have written
   8
   9         local termkey = require("termkey")
  10
  11 Now, here's what you just imported.
  12
  13  - tk = termkey.new(t)
  14
  15    Returns tk, a garbage-collected TermKey* object (the garbage
  16    collection calls termkey_destroy, not termkey_free), or nil on error.
  17    t should be a table, where the following keys have meaning (all the
  18    booleans default to false).
  19
  20     - t["fd"] integer; the file descriptor to attach to tk. Defaults to 1.
  21
  22     - t["nointerpret"] boolean; true means "Do not interpret C0//DEL codes if possible"
  23
  24     - t["convertkp"] boolean; true means "Convert KP codes to regular keypresses"
  25
  26     - t["raw"] boolean; true means "Input is raw bytes, not UTF-8"
  27
  28     - t["utf8"] boolean; true means "Input is definitely UTF-8"
  29
  30     - t["notermios"] boolean; true means "Do not make initial termios calls on construction"
  31
  32     - t["spacesymbol"] boolean; true means "Sets TERMKEY_CANON_SPACESYMBOL"
  33
  34     - t["ctrlc"] boolean; true means "Allow Ctrl-C to be read as normal, disabling SIGINT"
  35
  36     - t["eintr"] boolean; true means "Return ERROR on signal (EINTR) rather than retry"
  37
  38     - t["nostart"] boolean; true means "Do not call termkey_start() in constructor"
  39
  40       Note: At the time of writing, with termkey 0.22, the following program
  41
  42           termkey=require('termkey')
  43           tk=termkey.new({ nostart = true })
  44           -- implicit end of program, and garbage collection of tk
  45
  46       is equivalent to
  47
  48           #include <termkey.h>
  49           int main(void)
  50           {
  51               TermKey *tk = termkey_new(1, TERMKEY_FLAG_NOSTART);
  52               termkey_destroy(tk);
  53
  54               return 0;
  55           }
  56
  57       which crashes (on my machine and with my $TERM, at least). I'm not
  58       going to put in convoluted workarounds for this -- wrapper
  59       libraries aren't the place for patches.
  60
  61  - tk:start() calls termkey_start(tk)
  62
  63  - tk:stop() calls termkey_stop(tk)
  64
  65  - tk:is_started() returns termkey_is_started(tk) as a boolean
  66
  67  - tk:get_fd() returns termkey_get_fd(tk) as an integer
  68
  69  - tk:get_flags() calls termkey_get_flags(tk), then returns it as a
  70    table such as
  71
  72      { "nointerpret" = false, "convertkp" = true, ... }
  73
  74    as described for termkey.new()
  75
  76  - tk:get_waittime() returns termkey_get_waittime(tk) as an integer
  77
  78  - tk:set_waittime(n) calls termkey_set_waittime(tk, n)
  79
  80  - tk:get_canonflags() returns something like
  81
  82      { spacesymbol = true, delbs = false }
  83
  84    based on termkey_get_canonflags(tk)
  85
  86  - tk:set_canonflags(t) calls termkey_set_canonflags(tk, flags), where
  87    flags is interpreted from the table, t, based on the format described
  88    above.
  89
  90  - tk:get_buffer_size() returns termkey_get_buffer_size(tk) as an
  91    integer. Note that get_buffer_size returns size_t, but Lua will
  92    convert this into Lua_integer, which could be smaller.
  93
  94  - tk:set_buffer_size(n) calls termkey_set_buffer_size(tk, n). As with
  95    get_buffer_size, n may be truncated during the translation.
  96
  97  - tk:get_buffer_remaining() returns termkey_get_buffer_remaining(tk) as
  98    an integer. See get_buffer_size.
  99
 100  - k = tk:getkey() calls termkey_getkey. If the result (the
 101    TermKeyResult) is TERMKEY_RES_NONE, k is nil. It might also be "eof",
 102    "again", or "error", corresponding to the appropriate return values
 103    of termkey_getkey.
 104
 105    Finally, if termkey_getkey returned TERMKEY_RES_KEY, then k is a
 106    table of the following form:
 107
 108      {
 109        codepoint = <a unicode codepoint, as an integer>
 110        function_number = <when F8 is pressed, this is 8>
 111        sym = <a string, see below>
 112        mouse = {
 113          event = <one of "unknown", "press", "drag", "release">,
 114          button = <integer>,
 115          line = <integer>,
 116          col = <integer>
 117        }
 118        modereport = {
 119          initial = <integer>,
 120          mode = <integer>,
 121          value = <integer>
 122        }
 123        position = {
 124          line = <integer>,
 125          col = <integer>
 126        }
 127        command_string = <string>
 128        csi = {
 129          args = <an array of integers>
 130          cmd = <integer>
 131        }
 132        -- exactly one of the above fields is present; the more complex
 133        -- fields are filled out according to the termkey_interpret_xyz
 134        -- family of functions.
 135
 136        shift = <boolean>
 137        alt = <boolean>
 138        ctrl = <boolean>
 139        -- the above fields correspond to the modifiers field of
 140        -- TermKeyKey and might be omitted, implying false
 141
 142        utf8 = <string>
 143        -- If the utf8 field of TermKeyKey contains a non-trivial string,
 144        -- it will be copied into this field, treated as a sequence of
 145        -- bytes.
 146      }
 147
 148    The value of the sym field is obtained by taking the name of the
 149    value in the TermKeyKey structure (something like
 150    "TERMKEY_SYM_DELETE"), deleting the "TERMKEY_SYM" prefix, and
 151    lower-casing the result (obtaining "delete"). This includes "unknown"
 152    and "none". In the impossible case of TERMKEY_N_SYMS, "unknown" is
 153    returned.