api: add metadata for ui events

runtime/doc/api.txt

@@ -48,6 +48,7 @@ version.api_compatible	API is backwards-compatible with this level
 version.api_prerelease	Declares the current API level as unstable >
 			(version.api_prerelease && fn.since == version.api_level)
 functions		API function signatures
+ui_events		UI event signatures |rpc-remote-ui|
 {fn}.since		API level where function {fn} was introduced
 {fn}.deprecated_since	API level where function {fn} was deprecated
 types			Custom handle types defined by Nvim

src/nvim/CMakeLists.txt

@@ -26,6 +26,7 @@ set(GENERATED_UI_EVENTS ${GENERATED_DIR}/ui_events.generated.h)
 set(GENERATED_UI_EVENTS_CALL ${GENERATED_DIR}/ui_events_call.generated.h)
 set(GENERATED_UI_EVENTS_REMOTE ${GENERATED_DIR}/ui_events_remote.generated.h)
 set(GENERATED_UI_EVENTS_BRIDGE ${GENERATED_DIR}/ui_events_bridge.generated.h)
+set(GENERATED_UI_EVENTS_METADATA ${GENERATED_DIR}/api/private/ui_events_metadata.generated.h)
 set(GENERATED_EX_CMDS_ENUM ${GENERATED_INCLUDES_DIR}/ex_cmds_enum.generated.h)
 set(GENERATED_EX_CMDS_DEFS ${GENERATED_DIR}/ex_cmds_defs.generated.h)
 set(GENERATED_FUNCS ${GENERATED_DIR}/funcs.generated.h)
@@ -269,12 +270,14 @@ add_custom_command(
          ${GENERATED_UI_EVENTS_CALL}
          ${GENERATED_UI_EVENTS_REMOTE}
          ${GENERATED_UI_EVENTS_BRIDGE}
+         ${GENERATED_UI_EVENTS_METADATA}
   COMMAND ${LUA_PRG} ${API_UI_EVENTS_GENERATOR} ${CMAKE_CURRENT_LIST_DIR}
                      ${CMAKE_CURRENT_LIST_DIR}/api/ui_events.in.h
                      ${GENERATED_UI_EVENTS}
                      ${GENERATED_UI_EVENTS_CALL}
                      ${GENERATED_UI_EVENTS_REMOTE}
                      ${GENERATED_UI_EVENTS_BRIDGE}
+                     ${GENERATED_UI_EVENTS_METADATA}
   DEPENDS
     ${API_UI_EVENTS_GENERATOR}
     ${CMAKE_CURRENT_LIST_DIR}/api/ui_events.in.h

src/nvim/api/private/helpers.c

@@ -33,6 +33,7 @@ typedef struct {
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "api/private/helpers.c.generated.h"
 # include "api/private/funcs_metadata.generated.h"
+# include "api/private/ui_events_metadata.generated.h"
 #endif
 
 /// Start block that may cause vimscript exceptions
@@ -820,6 +821,7 @@ Dictionary api_metadata(void)
   if (!metadata.size) {
     PUT(metadata, "version", DICTIONARY_OBJ(version_dict()));
     init_function_metadata(&metadata);
+    init_ui_event_metadata(&metadata);
     init_error_type_metadata(&metadata);
     init_type_metadata(&metadata);
   }
@@ -843,6 +845,22 @@ static void init_function_metadata(Dictionary *metadata)
   PUT(*metadata, "functions", functions);
 }
 
+static void init_ui_event_metadata(Dictionary *metadata)
+{
+  msgpack_unpacked unpacked;
+  msgpack_unpacked_init(&unpacked);
+  if (msgpack_unpack_next(&unpacked,
+                          (const char *)ui_events_metadata,
+                          sizeof(ui_events_metadata),
+                          NULL) != MSGPACK_UNPACK_SUCCESS) {
+    abort();
+  }
+  Object ui_events;
+  msgpack_rpc_to_object(&unpacked.data, &ui_events);
+  msgpack_unpacked_destroy(&unpacked);
+  PUT(*metadata, "ui_events", ui_events);
+}
+
 static void init_error_type_metadata(Dictionary *metadata)
 {
   Dictionary types = ARRAY_DICT_INIT;

src/nvim/api/ui_events.in.h

@@ -3,41 +3,69 @@
 
 // This file is not compiled, just parsed for definitons
 #ifdef INCLUDE_GENERATED_DECLARATIONS
-#error "don't include this file, include nvim/ui.h"
+# error "don't include this file, include nvim/ui.h"
 #endif
 
 #include "nvim/api/private/defs.h"
 #include "nvim/func_attr.h"
 #include "nvim/ui.h"
 
-void resize(Integer rows, Integer columns);
+void resize(Integer rows, Integer columns)
-void clear(void);
+    FUNC_API_SINCE(3);
-void eol_clear(void);
+void clear(void)
-void cursor_goto(Integer row, Integer col);
+    FUNC_API_SINCE(3);
-void mode_info_set(Boolean enabled, Array cursor_styles);
+void eol_clear(void)
-void update_menu(void);
+    FUNC_API_SINCE(3);
-void busy_start(void);
+void cursor_goto(Integer row, Integer col)
-void busy_stop(void);
+    FUNC_API_SINCE(3);
-void mouse_on(void);
+void mode_info_set(Boolean enabled, Array cursor_styles)
-void mouse_off(void);
+    FUNC_API_SINCE(3);
-void mode_change(String mode, Integer mode_idx);
+void update_menu(void)
-void set_scroll_region(Integer top, Integer bot, Integer left, Integer right);
+    FUNC_API_SINCE(3);
-void scroll(Integer count);
+void busy_start(void)
-void highlight_set(HlAttrs attrs) REMOTE_IMPL BRIDGE_IMPL;
+    FUNC_API_SINCE(3);
-void put(String str);
+void busy_stop(void)
-void bell(void);
+    FUNC_API_SINCE(3);
-void visual_bell(void);
+void mouse_on(void)
-void flush(void) REMOTE_IMPL;
+    FUNC_API_SINCE(3);
-void update_fg(Integer fg);
+void mouse_off(void)
-void update_bg(Integer bg);
+    FUNC_API_SINCE(3);
-void update_sp(Integer sp);
+void mode_change(String mode, Integer mode_idx)
-void suspend(void) BRIDGE_IMPL;
+    FUNC_API_SINCE(3);
-void set_title(String title);
+void set_scroll_region(Integer top, Integer bot, Integer left, Integer right)
-void set_icon(String icon);
+    FUNC_API_SINCE(3);
+void scroll(Integer count)
+    FUNC_API_SINCE(3);
+void highlight_set(HlAttrs attrs)
+    FUNC_API_SINCE(3) REMOTE_IMPL BRIDGE_IMPL;
+void put(String str)
+    FUNC_API_SINCE(3);
+void bell(void)
+    FUNC_API_SINCE(3);
+void visual_bell(void)
+    FUNC_API_SINCE(3);
+void flush(void)
+    FUNC_API_SINCE(3) REMOTE_IMPL;
+void update_fg(Integer fg)
+    FUNC_API_SINCE(3);
+void update_bg(Integer bg)
+    FUNC_API_SINCE(3);
+void update_sp(Integer sp)
+    FUNC_API_SINCE(3);
+void suspend(void)
+    FUNC_API_SINCE(3) BRIDGE_IMPL;
+void set_title(String title)
+    FUNC_API_SINCE(3);
+void set_icon(String icon)
+    FUNC_API_SINCE(3);
 
-void popupmenu_show(Array items, Integer selected, Integer row, Integer col) REMOTE_ONLY;
+void popupmenu_show(Array items, Integer selected, Integer row, Integer col)
-void popupmenu_hide(void) REMOTE_ONLY;
+    FUNC_API_SINCE(3) REMOTE_ONLY;
-void popupmenu_select(Integer selected) REMOTE_ONLY;
+void popupmenu_hide(void)
-void tabline_update(Tabpage current, Array tabs) REMOTE_ONLY;
+    FUNC_API_SINCE(3) REMOTE_ONLY;
+void popupmenu_select(Integer selected)
+    FUNC_API_SINCE(3) REMOTE_ONLY;
+void tabline_update(Tabpage current, Array tabs)
+    FUNC_API_SINCE(3) REMOTE_ONLY;
 
 #endif  // NVIM_API_UI_EVENTS_IN_H

src/nvim/generators/gen_api_ui_events.lua

@@ -3,12 +3,13 @@ mpack = require('mpack')
 local nvimdir = arg[1]
 package.path = nvimdir .. '/?.lua;' .. package.path
 
-assert(#arg == 6)
+assert(#arg == 7)
 input = io.open(arg[2], 'rb')
 proto_output = io.open(arg[3], 'wb')
 call_output = io.open(arg[4], 'wb')
 remote_output = io.open(arg[5], 'wb')
 bridge_output = io.open(arg[6], 'wb')
+metadata_output = io.open(arg[7], 'wb')
 
 c_grammar = require('generators.c_grammar')
 local events = c_grammar.grammar:match(input:read('*all'))
@@ -53,6 +54,12 @@ for i = 1, #events do
   ev = events[i]
   assert(ev.return_type == 'void')
 
+  if ev.since == nil then
+    print("Ui event "..ev.name.." lacks since field.\n")
+    os.exit(1)
+  end
+  ev.since = tonumber(ev.since)
+
   if not ev.remote_only then
     proto_output:write('  void (*'..ev.name..')')
     write_signature(proto_output, ev, 'UI *ui')
@@ -134,3 +141,20 @@ end
 proto_output:close()
 call_output:close()
 remote_output:close()
+
+-- don't expose internal attributes like "impl_name" in public metadata
+exported_attributes = {'name', 'parameters',
+                       'since', 'deprecated_since'}
+exported_events = {}
+for _,ev in ipairs(events) do
+  local f_exported = {}
+  for _,attr in ipairs(exported_attributes) do
+    f_exported[attr] = ev[attr]
+  end
+  exported_events[#exported_events+1] = f_exported
+end
+
+packed = mpack.pack(exported_events)
+dump_bin_array = require("generators.dump_bin_array")
+dump_bin_array(metadata_output, 'ui_events_metadata', packed)
+metadata_output:close()

test/functional/eval/api_functions_spec.lua

@@ -106,7 +106,7 @@ describe('api functions', function()
 
   it('have metadata accessible with api_info()', function()
     local api_keys = eval("sort(keys(api_info()))")
-    eq({'error_types', 'functions', 'types', 'version'}, api_keys)
+    eq({'error_types', 'functions', 'types', 'ui_events', 'version'}, api_keys)
   end)
 
   it('are highlighted by vim.vim syntax file', function()

test/functional/eval/msgpack_functions_spec.lua

@@ -461,7 +461,7 @@ describe('msgpackparse() function', function()
     eval(cmd)
     eval(cmd)  -- do it again (try to force segfault)
     local api_info = eval(cmd)  -- do it again
-    eq({'error_types', 'functions', 'types', 'version'}, api_info)
+    eq({'error_types', 'functions', 'types', 'ui_events', 'version'}, api_info)
   end)
 
   it('fails when called with no arguments', function()