fix(api): validation, documentation of hl_group #31195

Problem:  Documentation for "hl_group" in nvim_buf_set_extmark() is
          unclear. "hl_group" in nvim_echo() does not accept
          highlight group id.
Solution: Move documentation for highlight group name/id to first
          mention of hl_group. Update nvim_echo() to accept highlight
          group id.

runtime/doc/api.txt

@@ -658,8 +658,8 @@ nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
 
     Parameters: ~
       • {chunks}   A list of `[text, hl_group]` arrays, each representing a
-                   text chunk with specified highlight. `hl_group` element can
+                   text chunk with specified highlight group name or ID.
-                   be omitted for no highlight.
+                   `hl_group` element can be omitted for no highlight.
       • {history}  if true, add to |message-history|.
       • {opts}     Optional parameters.
                    • verbose: Message is printed as a result of 'verbose'
@@ -2672,8 +2672,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                   • id : id of the extmark to edit.
                   • end_row : ending line of the mark, 0-based inclusive.
                   • end_col : ending col of the mark, 0-based exclusive.
-                  • hl_group : name of the highlight group used to highlight
+                  • hl_group : highlight group used for the text range. This
-                    this mark.
+                    and below highlight groups can be supplied either as a
+                    string or as an integer, the latter of which can be
+                    obtained using |nvim_get_hl_id_by_name()|.
                   • hl_eol : when true, for a multiline highlight covering the
                     EOL of a line, continue the highlight for the rest of the
                     screen line (just like for diff and cursorline highlight).
@@ -2682,9 +2684,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     with specified highlight. `highlight` element can either
                     be a single highlight group, or an array of multiple
                     highlight groups that will be stacked (highest priority
-                    last). A highlight group can be supplied either as a
+                    last).
-                    string or as an integer, the latter which can be obtained
-                    using |nvim_get_hl_id_by_name()|.
                   • virt_text_pos : position of virtual text. Possible values:
                     • "eol": right after eol character (default).
                     • "overlay": display over the specified column, without
@@ -2750,15 +2750,14 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     buffer or end of the line respectively. Defaults to true.
                   • sign_text: string of length 1-2 used to display in the
                     sign column.
-                  • sign_hl_group: name of the highlight group used to
+                  • sign_hl_group: highlight group used for the sign column
-                    highlight the sign column text.
+                    text.
-                  • number_hl_group: name of the highlight group used to
+                  • number_hl_group: highlight group used for the number
-                    highlight the number column.
+                    column.
-                  • line_hl_group: name of the highlight group used to
+                  • line_hl_group: highlight group used for the whole line.
-                    highlight the whole line.
+                  • cursorline_hl_group: highlight group used for the sign
-                  • cursorline_hl_group: name of the highlight group used to
+                    column text when the cursor is on the same line as the
-                    highlight the sign column text when the cursor is on the
+                    mark and 'cursorline' is enabled.
-                    same line as the mark and 'cursorline' is enabled.
                   • conceal: string which should be either empty or a single
                     character. Enable concealing similar to |:syn-conceal|.
                     When a character is supplied it is used as |:syn-cchar|.

runtime/lua/vim/_meta/api.lua

@@ -592,8 +592,9 @@ function vim.api.nvim_buf_line_count(buffer) end
 --- - id : id of the extmark to edit.
 --- - end_row : ending line of the mark, 0-based inclusive.
 --- - end_col : ending col of the mark, 0-based exclusive.
---- - hl_group : name of the highlight group used to highlight
+--- - hl_group : highlight group used for the text range. This and below
----     this mark.
+---     highlight groups can be supplied either as a string or as an integer,
+---     the latter of which can be obtained using `nvim_get_hl_id_by_name()`.
 --- - hl_eol : when true, for a multiline highlight covering the
 ---            EOL of a line, continue the highlight for the rest
 ---            of the screen line (just like for diff and
@@ -603,9 +604,7 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---     text chunk with specified highlight. `highlight` element
 ---     can either be a single highlight group, or an array of
 ---     multiple highlight groups that will be stacked
----     (highest priority last). A highlight group can be supplied
+---     (highest priority last).
----     either as a string or as an integer, the latter which
----     can be obtained using `nvim_get_hl_id_by_name()`.
 --- - virt_text_pos : position of virtual text. Possible values:
 ---   - "eol": right after eol character (default).
 ---   - "overlay": display over the specified column, without
@@ -676,15 +675,12 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---     buffer or end of the line respectively. Defaults to true.
 --- - sign_text: string of length 1-2 used to display in the
 ---     sign column.
---- - sign_hl_group: name of the highlight group used to
+--- - sign_hl_group: highlight group used for the sign column text.
----     highlight the sign column text.
+--- - number_hl_group: highlight group used for the number column.
---- - number_hl_group: name of the highlight group used to
+--- - line_hl_group: highlight group used for the whole line.
----     highlight the number column.
+--- - cursorline_hl_group: highlight group used for the sign
---- - line_hl_group: name of the highlight group used to
+---     column text when the cursor is on the same line as the
----     highlight the whole line.
+---     mark and 'cursorline' is enabled.
---- - cursorline_hl_group: name of the highlight group used to
----     highlight the sign column text when the cursor is on
----     the same line as the mark and 'cursorline' is enabled.
 --- - conceal: string which should be either empty or a single
 ---     character. Enable concealing similar to `:syn-conceal`.
 ---     When a character is supplied it is used as `:syn-cchar`.
@@ -1106,8 +1102,8 @@ function vim.api.nvim_del_var(name) end
 --- Echo a message.
 ---
 --- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
---- text chunk with specified highlight. `hl_group` element
+--- text chunk with specified highlight group name or ID.
---- can be omitted for no highlight.
+--- `hl_group` element can be omitted for no highlight.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
 --- - verbose: Message is printed as a result of 'verbose' option.

src/nvim/api/extmark.c

@@ -381,8 +381,9 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///               - id : id of the extmark to edit.
 ///               - end_row : ending line of the mark, 0-based inclusive.
 ///               - end_col : ending col of the mark, 0-based exclusive.
-///               - hl_group : name of the highlight group used to highlight
+///               - hl_group : highlight group used for the text range. This and below
-///                   this mark.
+///                   highlight groups can be supplied either as a string or as an integer,
+///                   the latter of which can be obtained using |nvim_get_hl_id_by_name()|.
 ///               - hl_eol : when true, for a multiline highlight covering the
 ///                          EOL of a line, continue the highlight for the rest
 ///                          of the screen line (just like for diff and
@@ -392,9 +393,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///                   text chunk with specified highlight. `highlight` element
 ///                   can either be a single highlight group, or an array of
 ///                   multiple highlight groups that will be stacked
-///                   (highest priority last). A highlight group can be supplied
+///                   (highest priority last).
-///                   either as a string or as an integer, the latter which
-///                   can be obtained using |nvim_get_hl_id_by_name()|.
 ///               - virt_text_pos : position of virtual text. Possible values:
 ///                 - "eol": right after eol character (default).
 ///                 - "overlay": display over the specified column, without
@@ -465,15 +464,12 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 ///                   buffer or end of the line respectively. Defaults to true.
 ///               - sign_text: string of length 1-2 used to display in the
 ///                   sign column.
-///               - sign_hl_group: name of the highlight group used to
+///               - sign_hl_group: highlight group used for the sign column text.
-///                   highlight the sign column text.
+///               - number_hl_group: highlight group used for the number column.
-///               - number_hl_group: name of the highlight group used to
+///               - line_hl_group: highlight group used for the whole line.
-///                   highlight the number column.
+///               - cursorline_hl_group: highlight group used for the sign
-///               - line_hl_group: name of the highlight group used to
+///                   column text when the cursor is on the same line as the
-///                   highlight the whole line.
+///                   mark and 'cursorline' is enabled.
-///               - cursorline_hl_group: name of the highlight group used to
-///                   highlight the sign column text when the cursor is on
-///                   the same line as the mark and 'cursorline' is enabled.
 ///               - conceal: string which should be either empty or a single
 ///                   character. Enable concealing similar to |:syn-conceal|.
 ///                   When a character is supplied it is used as |:syn-cchar|.

src/nvim/api/private/helpers.c

@@ -771,7 +771,7 @@ int object_to_hl_id(Object obj, const char *what, Error *err)
     int id = (int)obj.data.integer;
     return (1 <= id && id <= highlight_num_groups()) ? id : 0;
   } else {
-    api_set_error(err, kErrorTypeValidation, "Invalid highlight: %s", what);
+    api_set_error(err, kErrorTypeValidation, "Invalid hl_group: %s", what);
     return 0;
   }
 }
@@ -809,27 +809,22 @@ HlMessage parse_hl_msg(Array chunks, Error *err)
 {
   HlMessage hl_msg = KV_INITIAL_VALUE;
   for (size_t i = 0; i < chunks.size; i++) {
-    if (chunks.items[i].type != kObjectTypeArray) {
+    VALIDATE_T("chunk", kObjectTypeArray, chunks.items[i].type, {
-      api_set_error(err, kErrorTypeValidation, "Chunk is not an array");
       goto free_exit;
-    }
+    });
     Array chunk = chunks.items[i].data.array;
-    if (chunk.size == 0 || chunk.size > 2
+    VALIDATE((chunk.size > 0 && chunk.size <= 2 && chunk.items[0].type == kObjectTypeString),
-        || chunk.items[0].type != kObjectTypeString
+             "%s", "Invalid chunk: expected Array with 1 or 2 Strings", {
-        || (chunk.size == 2 && chunk.items[1].type != kObjectTypeString)) {
-      api_set_error(err, kErrorTypeValidation,
-                    "Chunk is not an array with one or two strings");
       goto free_exit;
-    }
+    });
 
     String str = copy_string(chunk.items[0].data.string, NULL);
 
     int hl_id = 0;
     if (chunk.size == 2) {
-      String hl = chunk.items[1].data.string;
+      hl_id = object_to_hl_id(chunk.items[1], "text highlight", err);
-      if (hl.size > 0) {
+      if (ERROR_SET(err)) {
-        // TODO(bfredl): use object_to_hl_id and allow integer
+        goto free_exit;
-        hl_id = syn_check_group(hl.data, hl.size);
       }
     }
     kv_push(hl_msg, ((HlMessageChunk){ .text = str, .hl_id = hl_id }));

src/nvim/api/vim.c

@@ -779,8 +779,8 @@ void nvim_set_vvar(String name, Object value, Error *err)
 /// Echo a message.
 ///
 /// @param chunks  A list of `[text, hl_group]` arrays, each representing a
-///                text chunk with specified highlight. `hl_group` element
+///                text chunk with specified highlight group name or ID.
-///                can be omitted for no highlight.
+///                `hl_group` element can be omitted for no highlight.
 /// @param history  if true, add to |message-history|.
 /// @param opts  Optional parameters.
 ///          - verbose: Message is printed as a result of 'verbose' option.

test/functional/api/vim_spec.lua

@@ -3582,6 +3582,15 @@ describe('API', function()
       command('highlight Special guifg=SlateBlue')
     end)
 
+    it('validation', function()
+      eq("Invalid 'chunk': expected Array, got String", pcall_err(api.nvim_echo, { 'msg' }, 1, {}))
+      eq(
+        'Invalid chunk: expected Array with 1 or 2 Strings',
+        pcall_err(api.nvim_echo, { { '', '', '' } }, 1, {})
+      )
+      eq('Invalid hl_group: text highlight', pcall_err(api.nvim_echo, { { '', false } }, 1, {}))
+    end)
+
     it('should clear cmdline message before echo', function()
       feed(':call nvim_echo([["msg"]], v:false, {})<CR>')
       screen:expect {
@@ -3606,6 +3615,18 @@ describe('API', function()
         msg_a{15:msg_b}{16:msg_c}                         |
       ]],
       }
+      async_meths.nvim_echo({
+        { 'msg_d' },
+        { 'msg_e', api.nvim_get_hl_id_by_name('Statement') },
+        { 'msg_f', api.nvim_get_hl_id_by_name('Special') },
+      }, true, {})
+      screen:expect {
+        grid = [[
+        ^                                        |
+        {1:~                                       }|*6
+        msg_d{15:msg_e}{16:msg_f}                         |
+      ]],
+      }
     end)
 
     it('can show highlighted multiline', function()