fix(highlight): accept NONE as a color name (#17487)

... for when `ns=0`.

Also update the documentation of nvim_set_hl to clarify the set
behaviour.

Fixes #17478

src/nvim/api/vim.c

@@ -124,6 +124,10 @@ Dictionary nvim__get_hl_defs(Integer ns_id, Error *err)
 
 /// Set a highlight group.
 ///
+/// Note: unlike the `:highlight` command which can update a highlight group,
+/// this function completely replaces the definition. For example:
+/// `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'.
+///
 /// @param ns_id number of namespace for this highlight. Use value 0
 ///              to set a highlight group in the global (`:highlight`)
 ///              namespace.

src/nvim/highlight.c

@@ -927,10 +927,11 @@ int object_to_color(Object val, char *key, bool rgb, Error *err)
   } else if (val.type == kObjectTypeString) {
     String str = val.data.string;
     // TODO(bfredl): be more fancy with "bg", "fg" etc
+    if (!str.size || STRICMP(str.data, "NONE") == 0) {
+      return -1;
+    }
     int color;
-    if (!str.size) {
+    if (rgb) {
-      color = 0;
-    } else if (rgb) {
       color = name_to_color(str.data);
     } else {
       color = name_to_ctermcolor(str.data);

test/functional/api/highlight_spec.lua

@@ -304,10 +304,6 @@ describe("API: set highlight", function()
     eq('Test_hl3       xxx ctermbg=9',
       exec_capture('highlight Test_hl3'))
 
-    meths.set_hl(0, 'Test_hl3', {})
-    eq('Test_hl3       xxx cleared',
-      exec_capture('highlight Test_hl3'))
-
     eq("'redd' is not a valid color",
       pcall_err(meths.set_hl, 0, 'Test_hl3', {fg='redd'}))
 
@@ -320,5 +316,12 @@ describe("API: set highlight", function()
 
     eq("'#FF00FF' is not a valid color",
       pcall_err(meths.set_hl, 0, 'Test_hl3', {ctermfg='#FF00FF'}))
+
+    for _, fg_val in ipairs{ nil, 'NONE', 'nOnE', '', -1 } do
+      meths.set_hl(0, 'Test_hl3', {fg = fg_val})
+      eq('Test_hl3       xxx cleared',
+        exec_capture('highlight Test_hl3'))
+    end
+
   end)
 end)