nvim: yolokai: Sync with nvim-highlite upstream

nvim/.config/nvim/lua/yolokai.lua

@@ -1,109 +1,99 @@
 --[[ NOTHING INSIDE THIS FILE NEEDS TO BE EDITED BY THE USER. ]]
 
---[[
+--- A Neovim plugin to create more straightforward syntax for Lua `:map`ping and `:unmap`ping.
-	/*
+--- @module nvim-cartographer
-	 * IMPORTS
+--- @alias yolokai table
-	 */
---]]
 
-local vim = vim
+--[[/* VARS */]]
-local api = vim.api
-local exe = api.nvim_command
-local fn  = vim.fn
-local go  = vim.go
 
---[[
+--- Which set of colors to use.
-	/*
+local _USE_256 = tonumber(vim.go.t_Co) > 255 or string.find(vim.env.TERM, '256')
-	 * VARS
-	 */
---]]
 
--- These are constants for the indexes in the colors that were defined before.
+--- Indicating nothing for a highlight field.
-local _NONE         = 'NONE'
+local _NONE = 'NONE'
-local _PALETTE_256  = 2
+
-local _PALETTE_ANSI = 3
+--- Which index to use for `cterm` highlights.
+local _PALETTE_CTERM = _USE_256 and 2 or 3
+
+--- Which index to use for `gui` highlights.
 local _PALETTE_HEX  = 1
-local _TYPE_STRING  = 'string'
-local _TYPE_TABLE   = 'table'
 
--- Determine which set of colors to use.
+--- The `string` type.
-local _USE_HEX = go.termguicolors
+local _TYPE_STRING = 'string'
-local _USE_256 = tonumber(go.t_Co) > 255
-	or string.find(vim.env.TERM, '256')
 
---[[
+--- The `table` type.
-	/*
+local _TYPE_TABLE  = 'table'
-	 * HELPER FUNCTIONS
-	 */
---]]
 
--- Add the 'blend' parameter to some highlight command, if there is one.
+--[[/* HELPER FUNCTIONS */]]
-local function blend(command, attributes) -- {{{ †
-	if attributes.blend then -- There is a value for the `highlight-blend` field.
-		command[#command+1]=' blend='..attributes.blend
-	end
-end --}}} ‡
 
--- filter a highlight group's style information
+--- Filter out information not pertaining to styles
-local function filter_group_style(value)
+--- @param key string the field from `nvim_get_hl_by_name`
-	return value ~= 'background'
+--- @return boolean should_not_filter `true` if the field should not be filtered
-		and value ~= 'blend'
+local function filter_group_style(key)
-		and value ~= 'foreground'
+	return key ~= 'background'
-		and value ~= 'special'
+		and key ~= 'blend'
+		and key ~= 'foreground'
+		and key ~= 'special'
 end
 
--- Get the color value of a color variable, or "NONE" as a default.
+--- @param color string|table the color name or definition
+--- @param index number
+--- @return number|string color_value a hex, 16-bit, or ANSI color. "NONE" by default
 local function get(color, index) -- {{{ †
 	if type(color) == _TYPE_TABLE and color[index] then
 		return color[index]
 	elseif type(color) == _TYPE_STRING then
 		return color
-	else
+	end
-		return _NONE
+
+	return _NONE
+end --}}} ‡
+
+--- Take a `command` and add color-specifying components to it.
+--- @param command table the in-progress `:highlight` command
+--- @param definition table the definition of the highlight group
+local function colorize(command, definition) -- {{{ †
+	command[#command+1]=' guibg='..get(definition.bg, _PALETTE_HEX)..' guifg='..get(definition.fg, _PALETTE_HEX)
+		..' ctermbg='..get(definition.bg, _PALETTE_CTERM)..' ctermfg='..get(definition.fg, _PALETTE_CTERM)
+
+	-- Add the `blend` parameter if it is present
+	if definition.blend then -- There is a value for the `highlight-blend` field.
+		command[#command+1]=' blend='..definition.blend
 	end
 end --}}} ‡
 
---[[ If using hex and 256-bit colors, then populate the gui* and cterm* args.
+--- This function appends `selected_definition` to the end of `highlight_cmd`.
-	If using 16-bit colors, just populate the cterm* args. ]]
+--- @param command table the in-progress `:highlight` command
-local colorize = _USE_HEX and function(command, attributes) -- {{{ †
+--- @param style string the `gui`/`cterm` arguments to apply
-	command[#command+1]=' guibg='..get(attributes.bg, _PALETTE_HEX)..' guifg='..get(attributes.fg, _PALETTE_HEX)
+--- @param color string|table a `guisp` argument; same arg as `get`
-end or _USE_256 and function(command, attributes)
+--- @see get
-	command[#command+1]=' ctermbg='..get(attributes.bg, _PALETTE_256)..' ctermfg='..get(attributes.fg, _PALETTE_256)
+local function stylize(command, style, color)
-end or function(command, attributes)
+	command[#command+1]=' gui='..style..' cterm='..style
-	command[#command+1]=' ctermbg='..get(attributes.bg, _PALETTE_ANSI)..' ctermfg='..get(attributes.fg, _PALETTE_ANSI)
-end --}}} ‡
-
--- This function appends `selected_attributes` to the end of `highlight_cmd`.
-local stylize = _USE_HEX and function(command, style, color)
-	command[#command+1]=' gui='..style
 
 	if color then -- There is an undercurl color.
 		command[#command+1]=' guisp='..get(color, _PALETTE_HEX)
 	end
-end or function(command, style)
-	command[#command+1]=' cterm='..style
 end
 
+--- @param rgb string some string of RGB colors.
+--- @return string hex
 local function tohex(rgb) return string.format('#%06x', rgb) end
 
--- Load specific &bg instructions
+--- Create a metatable which prioritizes entries in the `&bg` index of `definition`
-local function use_background_with(attributes)
+--- @param definition table the definition of the highlight group
-	return setmetatable(
+--- @return table
-		attributes[go.background],
+local function use_background_with(definition)
-		{['__index'] = attributes}
+	return setmetatable(definition[vim.go.background], {__index = definition})
-	)
 end
 
---[[
+--[[/* MODULE */]]
-	/*
-	 * MODULE
-	 */
---]]
 
 local yolokai = {}
 
+--- @param group_name string
+--- @return table definition a nvim-yolokai compliant table describing `group_name`
 function yolokai.group(group_name)
-	local no_errors, group_definition = pcall(api.nvim_get_hl_by_name, group_name, go.termguicolors)
+	local no_errors, group_definition = pcall(vim.api.nvim_get_hl_by_name, group_name, vim.go.termguicolors)
 
 	if not no_errors then group_definition = {} end
 
@@ -113,64 +103,73 @@ function yolokai.group(group_name)
 		style.color = tohex(group_definition.special)
 	end
 
-	return {
+	return
-		['fg'] = group_definition.foreground and tohex(group_definition.foreground) or _NONE,
+	{
-		['bg'] = group_definition.background and tohex(group_definition.background) or _NONE,
+		fg = group_definition.foreground and tohex(group_definition.foreground) or _NONE,
-		['blend'] = group_definition.blend,
+		bg = group_definition.background and tohex(group_definition.background) or _NONE,
-		['style'] = style or _NONE
+		blend = group_definition.blend,
+		style = style or _NONE
 	}
 end
 
--- Generate a `:highlight` command from a group and some attributes.
+-- Generate a `:highlight` command from a group and some definition.
-function yolokai.highlight(highlight_group, attributes) -- {{{ †
+
+--- Generate and execute `:highlight` command from a group and some definition.
+--- @param highlight_group string the `{group-name}` argument for `:highlight`
+--- @param definition string|table a link or an attribute map
+function yolokai.highlight(highlight_group, definition) -- {{{ †
+	if type(definition) == _TYPE_STRING then -- `highlight_group` is a link to another group.
+		vim.api.nvim_command('hi! link '..highlight_group..' '..definition)
+		return
+	end
+
 	-- The base highlight command
 	local highlight_cmd = {'hi! ', highlight_group}
 
-	if type(attributes) == _TYPE_STRING then -- `highlight_group` is a link to another group.
+	-- Take care of special instructions for certain background colors.
-		highlight_cmd[3] = highlight_cmd[2]
+	if definition[vim.go.background] then
-		highlight_cmd[2] = 'link '
+		definition = use_background_with(definition)
-		highlight_cmd[4] = ' '
-		highlight_cmd[5] = attributes
-	else -- The `highlight_group` is uniquely defined.
-		-- Take care of special instructions for certain background colors.
-		if attributes[go.background] then
-			attributes = use_background_with(attributes)
-		end
-
-		colorize(highlight_cmd, attributes)
-		blend(highlight_cmd, attributes)
-
-		local style = attributes.style or _NONE
-
-		if type(style) == _TYPE_TABLE then
-			-- Concat all of the entries together with a comma between before styling.
-			stylize(highlight_cmd, table.concat(style, ','), style.color)
-		else -- The style is just a single entry.
-			stylize(highlight_cmd, style)
-		end
 	end
 
-	exe(table.concat(highlight_cmd))
+	colorize(highlight_cmd, definition)
+
+	local style = definition.style or _NONE
+
+	if type(style) == _TYPE_TABLE then
+		-- Concat all of the entries together with a comma between before styling.
+		stylize(highlight_cmd, table.concat(style, ','), style.color)
+	else -- The style is just a single entry.
+		stylize(highlight_cmd, style)
+	end
+
+	vim.api.nvim_command(table.concat(highlight_cmd))
 end --}}} ‡
 
-function yolokai:highlight_terminal(terminal_ansi_colors)
+--- Set `g:terminal_color_`s based on `terminal_colors`.
-	for index, color in ipairs(terminal_ansi_colors) do vim.g['terminal_color_'..(index-1)] =
+--- @param terminal_colors table a list 1..16 of colors to use in the terminal
-		go.termguicolors and color[_PALETTE_HEX] or color[_PALETTE_256] or get(color, _PALETTE_ANSI)
+function yolokai:highlight_terminal(terminal_colors)
+	for index, color in ipairs(terminal_colors) do vim.g['terminal_color_'..(index-1)] =
+		vim.go.termguicolors and color[_PALETTE_HEX] or color[_PALETTE_CTERM]
 	end
 end
 
-return setmetatable(yolokai, {['__call'] = function(self, normal, highlights, terminal_ansi_colors)
+return setmetatable(yolokai, {__call = function(self, normal, highlights, terminal_colors)
-	-- function to resolve function highlight groups being defined by function calls.
+	--- resolve highlight groups being defined by function calls.
+	--- @param tbl table the current table being indexed.
+	--- @param key string the key to resolve the value for.
+	--- @param resolve_links boolean whether to translate highlight links into full values
+	--- @returns the value at `tbl[key]`, when highlight links and embedded functions have been accounted for.
 	local function resolve(tbl, key, resolve_links)
 		local value = tbl[key]
 		local value_type = type(value)
-		if value_type == 'function' then
+
-			-- lazily cache the result; next time, if it isn't a function this step will be skipped
+		if value_type == 'function' then -- call and cache the result; next time, if it isn't a function this step will be skipped
-			tbl[key] = value(setmetatable({}, {
+			tbl[key] = value(setmetatable({},
-				['__index'] = function(_, inner_key) return resolve(tbl, inner_key, true) end
+			{
+				__index = function(_, inner_key) return resolve(tbl, inner_key, true) end
 			}))
-		elseif value_type == _TYPE_STRING and not string.find(value, '^#') and resolve_links then
+		elseif resolve_links and value_type == _TYPE_STRING and not string.find(value, '^#') then
-			return resolve(tbl, tbl[key], resolve_links)
+			return resolve(tbl, value, resolve_links)
 		end
 
 		return tbl[key]
@@ -180,14 +179,14 @@ return setmetatable(yolokai, {['__call'] = function(self, normal, highlights, te
 	local color_name = vim.g.colors_name
 
 	-- If the syntax has been enabled, reset it.
-	if fn.exists 'syntax_on' then exe 'syntax reset' end
+	if vim.fn.exists 'syntax_on' then vim.api.nvim_command 'syntax reset' end
 
 	-- replace the colors_name
 	vim.g.colors_name = color_name
 	color_name = nil
 
 	-- If we aren't using hex nor 256 colorsets.
-	if not (_USE_HEX or _USE_256) then go.t_Co = '16' end
+	if not (vim.go.termguicolors or _USE_256) then vim.go.t_Co = '16' end
 
 	-- Highlight the baseline.
 	self.highlight('Normal', normal)
@@ -198,5 +197,5 @@ return setmetatable(yolokai, {['__call'] = function(self, normal, highlights, te
 	end
 
 	-- Set the terminal highlight colors.
-	self:highlight_terminal(terminal_ansi_colors)
+	self:highlight_terminal(terminal_colors)
 end})