feat(api): add nvim_get_hl

[nullchilly]

Close #22679

:lua=vim.api.nvim_get_hl(0, { name = "Normal" })
{
  bg = "#282c34",
  ctermbg = 236,
  ctermfg = 146,
  fg = "#abb2bf"
}

:lua=vim.api.nvim_get_hl(0, { id = 8 })
{
  bg = "#5c6370",
  fg = "#e5c07b"
}

:lua=vim.api.nvim_get_hl(0, {})
{
  ALEError = {
    ctermfg = 204,
    fg = "#e06c75",
    underline = true
  },
  ALEErrorSign = {
    ctermfg = 204,
    fg = "#e06c75"
  },
  ALEInfo = {
    underline = true
  },
}

[zeertzjq]

Consider adding tests in test/functional/api/highlight_spec.lua

[justinmk]

Does this fully replace these functions:

nvim_get_hl_by_id
nvim_get_hl_by_name
nvim_get_hl_id_by_name

if not, what is needed to fully replace and deprecate those functions?

[lewis6991]

I would be good to clarify that "hex representation" means a string. The integer form can already be printed as hex using builtin features. I would expect consumers to mostly use decimal and use string.format('%x') when they want to stringify it.

In fact I would much prefer if hex mode outputted colors as 3 value tuples (e.g. {255, 0, 50}) as it would allow me to remove this monstrosity from my colorscheme:

---@param c1 integer color1
---@param c2 integer color2
---@param ration number
---@return integer Merged color
local function merge(c1, c2, ratio)
  ratio = ratio or 0.5
  assert(ratio <= 1 and ratio >= 0)
  local r1 = bit.arshift(bit.band(c1, 0xFF0000), 16)
  local r2 = bit.arshift(bit.band(c2, 0xFF0000), 16)
  local g1 = bit.arshift(bit.band(c1, 0x00FF00), 8)
  local g2 = bit.arshift(bit.band(c2, 0x00FF00), 8)
  local b1 = bit.band(c1, 0x0000FF)
  local b2 = bit.band(c2, 0x0000FF)

  local r = bit.band((r1 * ratio) + (r2 * (1 - ratio)), 0xFF)
  local g = bit.band((g1 * ratio) + (g2 * (1 - ratio)), 0xFF)
  local b = bit.band((b1 * ratio) + (b2 * (1 - ratio)), 0xFF)

  return bit.lshift(r, 16) + bit.lshift(g, 8) + b
end

[nullchilly]

I don't think so, the initial goal of this function is to manipulate colorscheme, I think "#1e1e2e" is better default than 113392728

[lewis6991]

How do you manipulate a colorscheme with the string form? I've only ever manipulated using the integer form (as above).

I think you're confusing types with number bases. A number can be represented as any base, it just happens that Lua's print uses base 10. What's more useful is separating the RGB components.

[nullchilly]

From the discussion in the linked issue, the colorscheme shouldn't change definition after this function

local hl_groups = vim.api.nvim_get_hl(0, {})
for name, spec in pairs(hl_groups) do
  vim.api.nvim_set_hl(0, name, spec)
end

[nullchilly]

I guess we can have hex as an integer option, like this:

1. integer
2. #rrggbb
3. (r, g, b)

What do you think?

[lewis6991]

If we add {r,g,b} then we should probably adjust nvim_set_hl to accept this form too.

nvim_get_hl is pretty low level, so I'm not sure how much value there is in it effectviely just doing string.format('#%x', color). Like we've said, it isn't needed for the nvim_get_hl -> nvim_set_hl flow to work.

Are there other uses cases you intended this for?

Maybe some utility function that takes a spec and prints it into an equivalent :hi output might fit better?

[nullchilly]

Maybe some utility function that takes a spec and prints it into an equivalent :hi output might fit better?

+1

Should I remove the hex option from this PR?

[bfredl]

Now that we have bit guaranteed in the lua stdlib, we can add further (pure-lua) helper functions to split a 24-bit integer into three 8-bit integers and vice versa. It doesn't need to be present in the language-independent API-interface.

[lewis6991]

Should I remove the hex option from this PR?

That would be my vote unless there's a use case I'm not aware of.

[nullchilly]

Removed in the recent commit.

[max397574]

how does this handle links?
does it return {link="xxx"} or the actual colors?
and what about the undefined hl groups (the weird [true] = x stuff which was mentioned in the og issue)

[nullchilly]

It's default to return { link = "xxx" } right now, I'm thinking of an option name for actual colors

The weird [true] = x are skipped by default with undefined = false option.

[max397574]

what if you set undefined=true though?
will it just return empty tables?

[nullchilly]

It will still return [true] = 6, this is the behavior of Dictionary to lua table

I can prevent this by pushing a ghost value into Dictionary but this seems like a hack

cc @clason

[bfredl]

@nullchilly the { [true] = 6 } issue will be fixed in #22737. No ghost value or further change will be needed in this PR.

[echasnovski]

I am a bit late to discussion (only discovered this PR), but I would like to suggest the following API for getting highlight groups:

• nvim_get_hl(ns_id, name, opts) should be exact counter part to nvim_set_hl(ns_id, name, val). In a sense that both of the following should be true:

cur_hl = vim.api.nvim_get_hl(0, "Comment", <any allowed options>)
vim.api.nvim_set_hl(0, "Comment", cur_hl)
new_hl = vim.api.nvim_get_hl(0, "Comment", <same options>)
-- `cur_hl` and `new_hl` should be the same

vim.api.nvim_set_hl(0, "Comment", <any allowed dictionary>)
cur_hl = vim.api.nvim_get_hl(0, "Comment", <any allowed options>)
vim.api.nvim_set_hl(0, "Comment", cur_hl)
-- Calling `:hi Comment` before and right now should display same value

Right now it means to return only one highlight group data, not all.

• nvim_list_hls(ns_id, opts) returns an array of names or ids (as per some use_id option) of all highlight group in ns_id namespace.
• nvim_get_hl_id_by_name(name) is same as now.

[lewis6991]

nvim_get_hl(ns_id, name, opts) should be exact counter part to nvim_set_hl(ns_id, name, val). In a sense that both of the following should be true:

Yes, I think that is a desired outcome here.

I think this PR is still good that it can handle multiple highlights since it allows us to deprecate several older API's.

I think a solution could be to allow nvim_set_hl (or some variant), to handle setting multiple highlight groups?

nvim_list_hls(ns_id, opts) returns an array of names or ids (as per some use_id option) of all highlight group in ns_id namespace.

I do like this idea and this could allow us to deprecate nvim_get_hl_id_by_name if we can add the id in there in such a way that it still works with nvim_set_hl. Maybe we can return a table<string,integer> instead of string[]?

[nullchilly]

I think we can simply overload vim.api.nvim_get_hl in lua to do this. Maybe something like this will work?

local nvim_get_hl = vim.api.nvim_get_hl

vim.api.nvim_get_hl = function(a, b, c)
	if type(b) == "string" then
		c.name = b
		return nvim_get_hl(a, c)
	end
	return nvim_get_hl(a, b)
end

:lua=vim.api.nvim_get_hl(0, "Comment", {})                                                        
{                                                                                                 
  fg = 7106694                                                                                    
}

[echasnovski]

I think a solution could be to allow nvim_set_hl (or some variant), to handle setting multiple highlight groups?

I thought about it and had no other objections except nvim_set_hl() as a name highly suggests that it returns single highlight group.

I do like this idea and this could allow us to deprecate nvim_get_hl_id_by_name if we can add the id in there in such a way that it still works with nvim_set_hl. Maybe we can return a table<string,integer> instead of string[]?

Yes, it would be great to only have nvim_list_hls().

If I understand you correctly, you suggest that it would return something like { Comment = 130, ... }? It is, of course, doable, but output is not an array (or list, however it is preferred to call here). If made an array like { { 'Comment', 130 }, ... } then it makes it hard to replicate nvim_get_hl_id_by_name() (doable, of course, but not straight forward). Maybe it is still worth it, as I don't think needing to know highlight group id is such a common operation, if both nvim_get_hl() and nvim_set_hl() accept groups names.

[clason]

Does this fully replace these functions:

nvim_get_hl_by_id
nvim_get_hl_by_name
nvim_get_hl_id_by_name

if not, what is needed to fully replace and deprecate those functions?

That is exactly the plan, yes. (Except the last one, which does something completely different despite the similar-looking name.

[nullchilly]

Consider adding tests in test/functional/api/highlight_spec.lua

Done!

[echasnovski]

Yes, I think that is a desired outcome here.

I think this PR is still good that it can handle multiple highlights since it allows us to deprecate several older API's.

But it is not how things are intended to be implemented right now:

• It has different signature: nvim_get_hl(ns_id, opts) instead of nvim_get_hl(ns_id, name, opts) as in nvim_set_hl(ns_id, name, val).
• To get data structure acceptable by nvim_set_hl(0, "Comment", val), nvim_get_hl() needs different call: nvim_get_hl(0, { name = "Comment" }) instead of nvim_get_hl(0, "Comment", {}).

Assuming changing signature of nvim_set_hl() is not acceptable, maybe something like this can be done to make nvim_get_hl() more aligned with nvim_set_hl():

• nvim_get_hl(ns_id, name, opts) where @param name string|number: if string then use as group name, if number then use as group id. If name is too obfuscated here, maybe name_or_id? The opts would only accept link at this point.
• nvim_set_hl(ns_id, name, val) would be updated to have same name usage.
• nvim_list_hls(ns_id) to get array of available highlights. Like { { 'Comment', 130 }, ... }. It can be suggested as a replacement for nvim_get_hl_id_by_name().

Another, more aligned with current suggestion approach is to allow name to be nil. In this case nvim_get_hl() returns dictionary with fields as group names while nvim_set_hl() accepts this structure and sets all of them. I am not a fan of this approach (as it means that output structure depends on parameter), but I guess it is also possible.

I really regret to not propose this sooner: didn't expect @nullchilly to be so eager to implement the feature :)

@clason, as you are the original author of the issue, what do you think about this?

[clason]

I really think the ns + optional filter is the correct approach -- I don't care about feeding the resulting table directly to nvim_set_hl vs wrapping this in a loop; all I care about is

1. there must be a method to retrieve all highlight groups in a namespace;
2. the returned highlight definition for a single group is can be fed directly to nvim_set_hl.
3. not adding another function that cannot deprecate at least two other functions

(and, of course, not changing signature of existing functions, which should go without saying due to the API contract -- which also prevents polyvalent signatures).

[echasnovski]

I really think the ns + optional filter is the correct approach -- I don't care about feeding the resulting table directly to nvim_set_hl vs wrapping this in a loop; all I care about is

1. there must be a method to retrieve all highlight groups in a namespace;

2. the returned highlight definition _for a single group_ is can be fed directly to `nvim_set_hl`.

3. not adding another function that cannot deprecate at least two other functions

(and, of course, not changing signature of existing functions, which should go without saying due to the API contract -- which also prevents polyvalent signatures).

Well, conditions 1 and 2 are satisfied. Condition 3 is satisfied with 2:3 ratio with a bonus of clearly more coherent API. If 1:2 is really a hard condition, then yes, it doesn't pass.

[nullchilly]

Is FUNC_API_SINCE(11) correct for nvim_get_hl?

Edit: Seems correct because

:lua=vim.version().api_level                                                                      
11

[clason]

LGTM, especially the API/docs. Nicely done!

[clason]

Merging this now so that it can get wider testing before 0.9; any issues with the implementation can be fixed in a follow-up PR (and, if necessary, backported to a 0.9.x).

[clason]

Thanks, @nullchilly!