docs(highlite): properly document module
This commit is contained in:
parent
f95263e2d0
commit
18b7ebb4b1
|
@ -1,10 +1,10 @@
|
||||||
--[[ NOTHING INSIDE THIS FILE NEEDS TO BE EDITED BY THE USER. ]]
|
--[[ 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 highlite table
|
||||||
*/
|
|
||||||
--]]
|
--[[/* IMPORTS */]]
|
||||||
|
|
||||||
local vim = vim
|
local vim = vim
|
||||||
local api = vim.api
|
local api = vim.api
|
||||||
|
@ -12,37 +12,41 @@ local exe = api.nvim_command
|
||||||
local fn = vim.fn
|
local fn = vim.fn
|
||||||
local go = vim.go
|
local go = vim.go
|
||||||
|
|
||||||
--[[
|
--[[/* VARS */]]
|
||||||
/*
|
|
||||||
* VARS
|
|
||||||
*/
|
|
||||||
--]]
|
|
||||||
|
|
||||||
-- Determine which set of colors to use.
|
--- Which set of colors to use.
|
||||||
local _USE_256 = tonumber(go.t_Co) > 255 or string.find(vim.env.TERM, '256')
|
local _USE_256 = tonumber(go.t_Co) > 255 or string.find(vim.env.TERM, '256')
|
||||||
|
|
||||||
-- 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'
|
||||||
|
|
||||||
|
--- Which index to use for `cterm` highlights.
|
||||||
local _PALETTE_CTERM = _USE_256 and 2 or 3
|
local _PALETTE_CTERM = _USE_256 and 2 or 3
|
||||||
|
|
||||||
|
--- Which index to use for `gui` highlights.
|
||||||
local _PALETTE_HEX = 1
|
local _PALETTE_HEX = 1
|
||||||
|
|
||||||
|
--- The `string` type.
|
||||||
local _TYPE_STRING = 'string'
|
local _TYPE_STRING = 'string'
|
||||||
|
|
||||||
|
--- The `table` type.
|
||||||
local _TYPE_TABLE = 'table'
|
local _TYPE_TABLE = 'table'
|
||||||
|
|
||||||
--[[
|
--[[/* HELPER FUNCTIONS */]]
|
||||||
/*
|
|
||||||
* HELPER FUNCTIONS
|
|
||||||
*/
|
|
||||||
--]]
|
|
||||||
|
|
||||||
-- 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
|
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) -- {{{ †
|
local function get(color, index) -- {{{ †
|
||||||
if type(color) == _TYPE_TABLE and color[index] then
|
if type(color) == _TYPE_TABLE and color[index] then
|
||||||
return color[index]
|
return color[index]
|
||||||
|
@ -53,8 +57,9 @@ local function get(color, index) -- {{{ †
|
||||||
end
|
end
|
||||||
end --}}} ‡
|
end --}}} ‡
|
||||||
|
|
||||||
--[[ If using hex and 256-bit colors, then populate the gui* and cterm* args.
|
--- Take a `command` and add color-specifying components to it.
|
||||||
If using 16-bit colors, just populate the cterm* args. ]]
|
--- @param command table the in-progress `:highlight` command
|
||||||
|
--- @param attributes table the definition of the highlight group
|
||||||
local function colorize(command, attributes) -- {{{ †
|
local function colorize(command, attributes) -- {{{ †
|
||||||
command[#command+1]=' guibg='..get(attributes.bg, _PALETTE_HEX)..' guifg='..get(attributes.fg, _PALETTE_HEX)
|
command[#command+1]=' guibg='..get(attributes.bg, _PALETTE_HEX)..' guifg='..get(attributes.fg, _PALETTE_HEX)
|
||||||
..' ctermbg='..get(attributes.bg, _PALETTE_CTERM)..' ctermfg='..get(attributes.fg, _PALETTE_CTERM)
|
..' ctermbg='..get(attributes.bg, _PALETTE_CTERM)..' ctermfg='..get(attributes.fg, _PALETTE_CTERM)
|
||||||
|
@ -65,7 +70,11 @@ local function colorize(command, attributes) -- {{{ †
|
||||||
end
|
end
|
||||||
end --}}} ‡
|
end --}}} ‡
|
||||||
|
|
||||||
-- This function appends `selected_attributes` to the end of `highlight_cmd`.
|
--- This function appends `selected_attributes` to the end of `highlight_cmd`.
|
||||||
|
--- @param command table the in-progress `:highlight` command
|
||||||
|
--- @param style string the `gui`/`cterm` arguments to apply
|
||||||
|
--- @param color string|table a `guisp` argument; same arg as `get`
|
||||||
|
--- @see get
|
||||||
local function stylize(command, style, color)
|
local function stylize(command, style, color)
|
||||||
command[#command+1]=' gui='..style..' cterm='..style
|
command[#command+1]=' gui='..style..' cterm='..style
|
||||||
|
|
||||||
|
@ -74,9 +83,13 @@ local function stylize(command, style, color)
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
|
--- @param rgb string some string of RGB colors.
|
||||||
|
--- @return string hex
|
||||||
local function tohex(rgb) return string.format('#%06x', rgb) end
|
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 `attributes`
|
||||||
|
--- @param attributes table the definition of the highlight group
|
||||||
|
--- @return table
|
||||||
local function use_background_with(attributes)
|
local function use_background_with(attributes)
|
||||||
return setmetatable(
|
return setmetatable(
|
||||||
attributes[go.background],
|
attributes[go.background],
|
||||||
|
@ -84,14 +97,12 @@ local function use_background_with(attributes)
|
||||||
)
|
)
|
||||||
end
|
end
|
||||||
|
|
||||||
--[[
|
--[[/* MODULE */]]
|
||||||
/*
|
|
||||||
* MODULE
|
|
||||||
*/
|
|
||||||
--]]
|
|
||||||
|
|
||||||
local highlite = {}
|
local highlite = {}
|
||||||
|
|
||||||
|
--- @param group_name string
|
||||||
|
--- @return table attributes a nvim-highlite compliant table describing `group_name`
|
||||||
function highlite.group(group_name)
|
function highlite.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(api.nvim_get_hl_by_name, group_name, go.termguicolors)
|
||||||
|
|
||||||
|
@ -112,6 +123,10 @@ function highlite.group(group_name)
|
||||||
end
|
end
|
||||||
|
|
||||||
-- Generate a `:highlight` command from a group and some attributes.
|
-- Generate a `:highlight` command from a group and some attributes.
|
||||||
|
|
||||||
|
--- Generate and execute `:highlight` command from a group and some attributes.
|
||||||
|
--- @param highlight_group string the `{group-name}` argument for `:highlight`
|
||||||
|
--- @param attributes table the definition of the highlight group
|
||||||
function highlite.highlight(highlight_group, attributes) -- {{{ †
|
function highlite.highlight(highlight_group, attributes) -- {{{ †
|
||||||
-- The base highlight command
|
-- The base highlight command
|
||||||
local highlight_cmd = {'hi! ', highlight_group}
|
local highlight_cmd = {'hi! ', highlight_group}
|
||||||
|
@ -142,8 +157,10 @@ function highlite.highlight(highlight_group, attributes) -- {{{ †
|
||||||
exe(table.concat(highlight_cmd))
|
exe(table.concat(highlight_cmd))
|
||||||
end --}}} ‡
|
end --}}} ‡
|
||||||
|
|
||||||
function highlite: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
|
||||||
|
function highlite:highlight_terminal(terminal_colors)
|
||||||
|
for index, color in ipairs(terminal_colors) do vim.g['terminal_color_'..(index-1)] =
|
||||||
go.termguicolors and color[_PALETTE_HEX] or color[_PALETTE_CTERM]
|
go.termguicolors and color[_PALETTE_HEX] or color[_PALETTE_CTERM]
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
Loading…
Reference in New Issue