Adds nvim_get_hl_by_name/by_id

...in order to retrieve highlights.

Added test/functional/api/highlight_spec.lua
HL_NORMAL is not really a good name, since it's more like an empty attribute than the normal's one.
If one pays attention, syn_cterm_attr2entry is never called with attr=0 because it's always special cased before.
I suggest in subsequent PRs we remove the ATTR_OFF and just insert an EMPTY ATTR/RESET_ATTR/UNINITIALIZED for id 0.

1 files changed, 37 insertions, 0 deletions

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index ab893a4c0f..0459d9235d 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -33,6 +33,7 @@
 #include "nvim/syntax.h"
 #include "nvim/getchar.h"
 #include "nvim/os/input.h"
+#include "nvim/ui.h"
 
 #define LINE_BUFFER_SIZE 4096
 
@@ -55,6 +56,42 @@ void nvim_command(String command, Error *err)
   try_end(err);
 }
 
+/// Retrieves highlight description from its name
+///
+/// @param name Highlight group name
+/// @return a highlight description e.g. {'bold': true, 'bg': 123, 'fg': 42}
+/// @see nvim_get_hl_by_id
+Dictionary nvim_get_hl_by_name(String name, Error *err)
+  FUNC_API_SINCE(3)
+{
+  Dictionary result = ARRAY_DICT_INIT;
+  int id = syn_name2id((const char_u *)name.data);
+
+  if (id == 0) {
+    api_set_error(err, kErrorTypeException, "Invalid highlight name %s",
+                  name.data);
+    return result;
+  }
+  result = nvim_get_hl_by_id(id, err);
+  return result;
+}
+
+/// Retrieves highlight description from its id
+///
+/// @param hl_id highlight id as returned by hlID()
+/// @see nvim_get_hl_by_name
+Dictionary nvim_get_hl_by_id(Integer hl_id, Error *err)
+  FUNC_API_SINCE(3)
+{
+  Dictionary dic = ARRAY_DICT_INIT;
+  if (syn_get_final_id((int)hl_id) == 0) {
+    api_set_error(err, kErrorTypeException, "Invalid highlight id %d", hl_id);
+    return dic;
+  }
+  int attrcode = syn_id2attr((int)hl_id);
+  return get_attr_by_id(attrcode, err);
+}
+
 /// Passes input keys to Nvim.
 /// On VimL error: Does not fail, but updates v:errmsg.
 ///