GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-15 16:51:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
luukvbaal
2024-11-17 00:36:11 +01:00
committed by GitHub
parent f85bc41c80
commit 9c718bc2bc
6 changed files with 69 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
runtime/doc/api.txt
View File

@ -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
be omitted for no highlight.
text chunk with specified highlight group name or ID.
`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
this mark.
• hl_group : highlight group used for the text range. This
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
string or as an integer, the latter which can be obtained
using |nvim_get_hl_id_by_name()|.
last).
• 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
highlight the sign column text.
• number_hl_group: name of the highlight group used to
highlight the number column.
• line_hl_group: name of the highlight group used to
highlight the whole line.
• 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.
• sign_hl_group: highlight group used for the sign column
text.
• number_hl_group: highlight group used for the number
column.
• line_hl_group: highlight group used for the whole line.
• cursorline_hl_group: highlight group used for 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|.

28
runtime/lua/vim/_meta/api.lua generated
View File

@ -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
--- this mark.
--- - hl_group : highlight group used for the text range. This 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
@ -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
--- either as a string or as an integer, the latter which
--- can be obtained using `nvim_get_hl_id_by_name()`.
--- (highest priority last).
--- - 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
--- highlight the sign column text.
--- - number_hl_group: name of the highlight group used to
--- highlight the number column.
--- - line_hl_group: name of the highlight group used to
--- highlight the whole line.
--- - 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.
--- - sign_hl_group: highlight group used for the sign column text.
--- - number_hl_group: highlight group used for the number column.
--- - line_hl_group: highlight group used for the whole line.
--- - cursorline_hl_group: highlight group used for 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
--- can be omitted for no highlight.
--- text chunk with specified highlight group name or ID.
--- `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.

24
src/nvim/api/extmark.c
View File

@ -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
/// this mark.
/// - hl_group : highlight group used for the text range. This 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
@ -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
/// either as a string or as an integer, the latter which
/// can be obtained using |nvim_get_hl_id_by_name()|.
/// (highest priority last).
/// - 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
/// highlight the sign column text.
/// - number_hl_group: name of the highlight group used to
/// highlight the number column.
/// - line_hl_group: name of the highlight group used to
/// highlight the whole line.
/// - 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.
/// - sign_hl_group: highlight group used for the sign column text.
/// - number_hl_group: highlight group used for the number column.
/// - line_hl_group: highlight group used for the whole line.
/// - cursorline_hl_group: highlight group used for 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|.

23
src/nvim/api/private/helpers.c
View File

@ -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) {
api_set_error(err, kErrorTypeValidation, "Chunk is not an array");
VALIDATE_T("chunk", kObjectTypeArray, chunks.items[i].type, {
goto free_exit;
}
});
Array chunk = chunks.items[i].data.array;
if (chunk.size == 0 || chunk.size > 2
|| chunk.items[0].type != kObjectTypeString
|| (chunk.size == 2 && chunk.items[1].type != kObjectTypeString)) {
api_set_error(err, kErrorTypeValidation,
"Chunk is not an array with one or two strings");
VALIDATE((chunk.size > 0 && chunk.size <= 2 && chunk.items[0].type == kObjectTypeString),
"%s", "Invalid chunk: expected Array with 1 or 2 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;
if (hl.size > 0) {
// TODO(bfredl): use object_to_hl_id and allow integer
hl_id = syn_check_group(hl.data, hl.size);
hl_id = object_to_hl_id(chunk.items[1], "text highlight", err);
if (ERROR_SET(err)) {
goto free_exit;
}
}
kv_push(hl_msg, ((HlMessageChunk){ .text = str, .hl_id = hl_id }));

4
src/nvim/api/vim.c
View File

@ -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
/// can be omitted for no highlight.
/// text chunk with specified highlight group name or ID.
/// `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.

21
test/functional/api/vim_spec.lua
View File

@ -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()