Initial documentation pass, and improvements to lua api ergonomics

Author: NicksWorld

docs/builtins/keybinding.rst

@@ -9,9 +9,9 @@ Like any other command, it can be used at any time from the console, but
 bindings are not remembered between runs of the game unless re-created in
 :file:`dfhack-config/init/dfhack.init`.
 
-Hotkeys can be any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12, or `
-(the key below the :kbd:`Esc` key on most keyboards). You can also represent
-mouse buttons beyond the first three with ``MOUSE4`` through ``MOUSE15``.
+Hotkeys can be any combinations of Ctrl/Alt/Shift with any key recognized by SDL.
+You can also represent mouse buttons beyond the first three with ``MOUSE4``
+through ``MOUSE15``.
 
 Usage
 -----
@@ -27,7 +27,7 @@ Usage
 ``keybinding set <key> "<cmdline>" ["<cmdline>" ...]``
     Clear, and then add bindings for the specified key.
 
-The ``<key>`` parameter above has the following **case-sensitive** syntax::
+The ``<key>`` parameter above has the following case-insensitive syntax::
 
     [Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
 

docs/dev/Lua API.rst

@@ -1430,6 +1430,46 @@ Job module
 
   Returns the job's description, as seen in the Units and Jobs screens.
 
+Hotkey module
+-------------
+
+* ``dfhack.hotkey.addKeybind(keyspec, command)``
+
+  Creates a new keybind with the provided keyspec (see the `keybinding` documentation
+  for details on format).
+  Returns false on failure to create keybind.
+
+* ``dfhack.hotkey.clearKeybind(keyspec, any_focus, command)``
+
+  Removes keybinds matching the provided keyspec.
+  If any_focus is true, the focus portion of the keyspec is ignored.
+  If command is not an empty string, the command is matched against as well.
+  Returns false if no keybinds were removed.
+
+* ``dfhack.hotkey.listActiveKeybinds()``
+
+  Returns a list of keybinds active within the current context.
+  The items are tables with the following attributes:
+  :spec: The keyspec for the hotkey
+  :command: The command the hotkey runs when pressed
+
+* ``dfhack.hotkey.listAllKeybinds()``
+
+  Returns a list of all keybinds currently registered.
+  The items are tables with the following attributes:
+  :spec: The keyspec for the hotkey
+  :command: The command the hotkey runs when pressed
+
+* ``dfhack.hotkey.requestKeybindInput()``
+
+  Requests that the next hotkey-compatible input is saved and not processed,
+  retrievable with ``dfhack.hotkey.readKeybindInput()``.
+
+* ``dfhack.hotkey.readKeybindInput()``
+
+  Reads the latest saved keybind input that was requested.
+  Returns a keyspec string for the input, or nil if no input is saved.
+
 Units module
 ------------
 

library/LuaApi.cpp

@@ -1885,10 +1885,16 @@ static void hotkey_requestKeybindingInput() {
     if (hotkey_mgr) hotkey_mgr->requestKeybindInput();
 }
 
-static std::string hotkey_readKeybindInput() {
+static int hotkey_readKeybindInput(lua_State *L) {
     auto hotkey_mgr = Core::getInstance().getHotkeyManager();
-    if (!hotkey_mgr) return "";
-    return hotkey_mgr->readKeybindInput();
+    auto input = hotkey_mgr->readKeybindInput();
+
+    if (input.empty()) {
+        lua_pushnil(L);
+    } else {
+        lua_pushlstring(L, input.data(), input.size());
+    }
+    return 1;
 }
 
 void hotkey_pushBindArray(lua_State *L, const std::vector<Hotkey::KeyBinding>& binds) {
@@ -1928,14 +1934,14 @@ static int hotkey_listAllKeybinds(lua_State *L) {
 static const luaL_Reg dfhack_hotkey_funcs[] = {
     { "listActiveKeybinds", hotkey_listActiveKeybinds },
     { "listAllKeybinds", hotkey_listAllKeybinds },
+    { "readKeybindInput", hotkey_readKeybindInput },
     { NULL, NULL }
 };
 
 static const LuaWrapper::FunctionReg dfhack_hotkey_module[] = {
     WRAPN(addKeybind, hotkey_addKeybind),
     WRAPN(clearKeybind, hotkey_clearKeybind),
     WRAPN(requestKeybindInput, hotkey_requestKeybindingInput),
-    WRAPN(readKeybindInput, hotkey_readKeybindInput),
     { NULL, NULL }
 };