Expose get_key_name under awful.keyboard as suggested by @Elv13

and change comments and declaration style to match the rest of the codebase

Signed-off-by: ArenaL5 <arenal5@gmx.com>

lib/awful/hotkeys_popup/widget.lua

@@ -184,7 +184,7 @@ function widget.new(args)
         -- For every key in every `awful.key` binding, the first non-nil result
         -- in this lists is chosen as a human-readable name:
         -- * the value corresponding to its keysym in this table;
-        -- * the UTF-8 representation as decided by awesome.get_key_name();
+        -- * the UTF-8 representation as decided by awful.keyboard.get_key_name();
         -- * the keysym name itself;
         -- If no match is found, the key name will not be translated, and will
         -- be presented to the user as-is. (This is useful for cheatsheets for
@@ -250,7 +250,7 @@ function widget.new(args)
     for k, v in pairs(awful.key.keygroups) do
         widget_instance._keygroups[k] = {}
         for k2, v2 in pairs(v) do
-            local keysym, keyprint = awesome.get_key_name(v2[1])
+            local keysym, keyprint = awful.keyboard.get_key_name(v2[1])
             widget_instance._keygroups[k][k2] =
                 widget_instance.labels[keysym] or keyprint or keysym or v2[1]
         end
@@ -312,7 +312,7 @@ function widget.new(args)
         local group = data.group or "none"
         self._group_list[group] = true
         if not target[group] then target[group] = {} end
-        local keysym, keyprint = awesome.get_key_name(key)
+        local keysym, keyprint = awful.keyboard.get_key_name(key)
         local keylabel = self.labels[keysym] or keyprint or keysym or key
         local new_key = {
             key = keylabel,

lib/awful/keyboard.lua

@@ -197,6 +197,29 @@ function module.remove_client_keybinding(key)
     return false
 end
 
+--- Get X11 keysym and a one-character representation from an Awesome keycode.
+--
+-- A "one-character representation" is a single UTF-8 representing the typical
+-- output from that keysym in a text editor (e.g. " " for space, "ñ" for
+-- n_tilde, "Ā" for A_macron). It usually matches the main engraving of the key
+-- for level-0 symbols (but lowercase).
+--
+-- Keycodes may be given in a string in any valid format for `awful.key`:
+-- "#" + keycode, the symkey name and the UTF-8 representation will all work.
+--
+-- If no suitable keysym is found, or a malformed keycode is given as an
+-- argument, this function will return (nil, nil)
+--
+-- @treturn[1] string keysym The keysym name
+-- @treturn[1] nil keysym If no valid keysym is found
+-- @treturn[2] string printsymbol The xkb_keysym_to_utf8 result
+-- @treturn[2] nil printsymbol If the keysym has no printable representation.
+-- @staticfct awful.keyboard.get_key_name
+function module.get_key_name(key)
+    return capi.awesome._get_key_name(key)
+end
+
+
 capi.client.connect_signal("scanning", function()
     capi.client.emit_signal("request::default_keybindings", "context")
 end)

luaa.c

@@ -417,9 +417,10 @@ get_modifier_name(int map_index)
     return 0; /* \0 */
 }
 
-// Helper function for luaA_get_key_name() below.
+/* Helper function for luaA_get_key_name() below.
-// Will return the UTF-32 codepoint IF AND ONLY IF the input is exactly one
+ * Will return the UTF-32 codepoint IF AND ONLY IF the input is exactly one
-// valid UTF-8 character. Otherwise, it will return zero.
+ * valid UTF-8 character. Otherwise, it will return zero.
+ */
 static uint32_t
 one_utf8_to_utf32(const char* input, const size_t length) {
     gunichar character = g_utf8_get_char_validated(input, length);
@@ -432,7 +433,7 @@ one_utf8_to_utf32(const char* input, const size_t length) {
     return character;
 }
 
-/** Get X11 keysym and a one-character representation from an Awesome keycode.
+/* Get X11 keysym and a one-character representation from an Awesome keycode.
  *
  * A "one-character representation" is a single UTF-8 representing the typical
  * output from that keysym in a text editor (e.g. " " for space, "ñ" for
@@ -449,7 +450,7 @@ one_utf8_to_utf32(const char* input, const size_t length) {
  * @treturn[1] nil keysym If no valid keysym is found
  * @treturn[2] string printsymbol The xkb_keysym_to_utf8 result
  * @treturn[2] nil printsymbol If the keysym has no printable representation.
- * @staticfct get_key_name
+ * @staticfct awful.keyboard.get_key_name
  */
 
 static int
@@ -1101,7 +1102,7 @@ luaA_init(xdgHandle* xdg, string_array_t *searchpath)
         { "xrdb_get_value", luaA_xrdb_get_value},
         { "kill", luaA_kill},
         { "sync", luaA_sync},
-        { "get_key_name", luaA_get_key_name},
+        { "_get_key_name", luaA_get_key_name},
         { NULL, NULL }
     };