refactor: rename vim.highlight => vim.hl

Problem:
- `vim.highlight` module does not follow `:help dev-name-common`, which
  documents the name for "highlight" as "hl".
- Shorter names are usually preferred.

Solution:
Rename `vim.highlight` to `vim.hl`.

This is not a breaking change until 2.0 (or maybe never).

runtime/doc/deprecated.txt

@@ -21,6 +21,7 @@ API
 
 LUA
 - vim.region()		Use |getregionpos()| instead.
+- *vim.highlight*	Renamed to |vim.hl|.
 
 DIAGNOSTICS
 - *vim.diagnostic.goto_next()*	Use |vim.diagnostic.jump()| with `{count=1, float=true}` instead.

runtime/doc/lsp.txt

@@ -464,7 +464,7 @@ Use |:Inspect| to view the highlights for a specific token. Use |:hi| or
     hi @lsp.mod.deprecated gui=strikethrough  " deprecated is crossed out
     hi @lsp.typemod.function.async guifg=Blue " async functions are blue
 <
-The value |vim.highlight.priorities|`.semantic_tokens` is the priority of the
+The value |vim.hl.priorities|`.semantic_tokens` is the priority of the
 `@lsp.type.*` highlights. The `@lsp.mod.*` and `@lsp.typemod.*` highlights
 have priorities one and two higher, respectively.
 
@@ -1780,8 +1780,8 @@ highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts})
       • {hl_group}   (`string`) Highlight group name
       • {opts}       (`table?`) Optional parameters:
                      • {priority}? (`integer`, default:
-                       `vim.highlight.priorities.semantic_tokens + 3`)
+                       `vim.hl.priorities.semantic_tokens + 3`) Priority for
-                       Priority for the applied extmark.
+                       the applied extmark.
 
 start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
     Start the semantic token highlighting engine for the given buffer with the

runtime/doc/lua-guide.txt

@@ -552,7 +552,7 @@ This means that if your callback itself takes an (even optional) argument, you
 must wrap it in `function() end` to avoid an error:
 >lua
     vim.api.nvim_create_autocmd('TextYankPost', {
-      callback = function() vim.highlight.on_yank() end
+      callback = function() vim.hl.on_yank() end
     })
 <
 (Since unused arguments can be omitted in Lua function definitions, this is
@@ -576,7 +576,7 @@ Instead of using a pattern, you can create a buffer-local autocommand (see
 Similarly to mappings, you can (and should) add a description using `desc`:
 >lua
     vim.api.nvim_create_autocmd('TextYankPost', {
-      callback = function() vim.highlight.on_yank() end,
+      callback = function() vim.hl.on_yank() end,
       desc = "Briefly highlight yanked text"
     })
 <

runtime/doc/lua.txt

@@ -636,13 +636,13 @@ A subset of the `vim.*` API is available in threads. This includes:
 
 
 ==============================================================================
-VIM.HIGHLIGHT                                                  *vim.highlight*
+VIM.HL                                                                *vim.hl*
 
-vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
+vim.hl.on_yank({opts})                                      *vim.hl.on_yank()*
     Highlight the yanked text during a |TextYankPost| event.
 
     Add the following to your `init.vim`: >vim
-        autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300}
+        autocmd TextYankPost * silent! lua vim.hl.on_yank {higroup='Visual', timeout=300}
 <
 
     Parameters: ~
@@ -655,9 +655,9 @@ vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
                   true)
                 • event event structure (default vim.v.event)
                 • priority integer priority (default
-                  |vim.highlight.priorities|`.user`)
+                  |vim.hl.priorities|`.user`)
 
-vim.highlight.priorities                            *vim.highlight.priorities*
+vim.hl.priorities                                          *vim.hl.priorities*
     Table with default priorities used for highlighting:
     • `syntax`: `50`, used for standard syntax highlighting
     • `treesitter`: `100`, used for treesitter-based highlighting
@@ -666,8 +666,8 @@ vim.highlight.priorities                            *vim.highlight.priorities*
     • `user`: `200`, used for user-triggered highlights such as LSP document
       symbols or `on_yank` autocommands
 
-                                                       *vim.highlight.range()*
+                                                              *vim.hl.range()*
-vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
+vim.hl.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
     Apply highlight group to range of text.
 
     Parameters: ~
@@ -684,8 +684,7 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
                    • {inclusive}? (`boolean`, default: `false`) Indicates
                      whether the range is end-inclusive
                    • {priority}? (`integer`, default:
-                     `vim.highlight.priorities.user`) Indicates priority of
+                     `vim.hl.priorities.user`) Highlight priority
-                     highlight
 
 
 ==============================================================================

runtime/doc/vim_diff.txt

@@ -249,7 +249,7 @@ backwards-compatibility cost. Some examples:
 
 Some features are built in that otherwise required external plugins:
 
-- Highlighting the yanked region, see |vim.highlight|.
+- Highlighting the yanked region, see |vim.hl|.
 
 ARCHITECTURE
 

runtime/lua/vim/_editor.lua

@@ -32,7 +32,7 @@ for k, v in pairs({
   func = true,
   F = true,
   lsp = true,
-  highlight = true,
+  hl = true,
   diagnostic = true,
   keymap = true,
   ui = true,
@@ -1197,4 +1197,7 @@ require('vim._options')
 ---@deprecated
 vim.loop = vim.uv
 
+-- Deprecated. Remove at Nvim 2.0
+vim.highlight = vim._defer_deprecated_module('vim.highlight', 'vim.hl')
+
 return vim

runtime/lua/vim/_meta.lua

@@ -15,7 +15,7 @@ vim.fs = require('vim.fs')
 vim.func = require('vim.func')
 vim.glob = require('vim.glob')
 vim.health = require('vim.health')
-vim.highlight = require('vim.highlight')
+vim.hl = require('vim.hl')
 vim.iter = require('vim.iter')
 vim.keymap = require('vim.keymap')
 vim.loader = require('vim.loader')

runtime/lua/vim/diagnostic.lua

@@ -1498,13 +1498,13 @@ M.handlers.underline = {
         end
       end
 
-      vim.highlight.range(
+      vim.hl.range(
         bufnr,
         underline_ns,
         higroup,
         { diagnostic.lnum, diagnostic.col },
         { diagnostic.end_lnum, diagnostic.end_col },
-        { priority = vim.highlight.priorities.diagnostics }
+        { priority = vim.hl.priorities.diagnostics }
       )
     end
     save_extmarks(underline_ns, bufnr)

runtime/lua/vim/hl.lua

@@ -17,7 +17,7 @@ M.priorities = {
   user = 200,
 }
 
---- @class vim.highlight.range.Opts
+--- @class vim.hl.range.Opts
 --- @inlinedoc
 ---
 --- Type of range. See [getregtype()]
@@ -28,8 +28,8 @@ M.priorities = {
 --- (default: `false`)
 --- @field inclusive? boolean
 ---
---- Indicates priority of highlight
+--- Highlight priority
---- (default: `vim.highlight.priorities.user`)
+--- (default: `vim.hl.priorities.user`)
 --- @field priority? integer
 
 --- Apply highlight group to range of text.
@@ -39,7 +39,7 @@ M.priorities = {
 ---@param higroup string Highlight group to use for highlighting
 ---@param start integer[]|string Start of region as a (line, column) tuple or string accepted by |getpos()|
 ---@param finish integer[]|string End of region as a (line, column) tuple or string accepted by |getpos()|
----@param opts? vim.highlight.range.Opts
+---@param opts? vim.hl.range.Opts
 function M.range(bufnr, ns, higroup, start, finish, opts)
   opts = opts or {}
   local regtype = opts.regtype or 'v'
@@ -124,7 +124,7 @@ local yank_cancel --- @type fun()?
 --- Add the following to your `init.vim`:
 ---
 --- ```vim
---- autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300}
+--- autocmd TextYankPost * silent! lua vim.hl.on_yank {higroup='Visual', timeout=300}
 --- ```
 ---
 --- @param opts table|nil Optional parameters
@@ -133,7 +133,7 @@ local yank_cancel --- @type fun()?
 ---              - on_macro  highlight when executing macro (default false)
 ---              - on_visual highlight when yanking visual selection (default true)
 ---              - event     event structure (default vim.v.event)
----              - priority  integer priority (default |vim.highlight.priorities|`.user`)
+---              - priority  integer priority (default |vim.hl.priorities|`.user`)
 function M.on_yank(opts)
   vim.validate({
     opts = {
@@ -145,7 +145,7 @@ function M.on_yank(opts)
           return type(t) == 'table'
         end
       end,
-      'a table or nil to configure options (see `:h highlight.on_yank`)',
+      'a table or nil to configure options (see `:h vim.hl.on_yank`)',
     },
   })
   opts = opts or {}

runtime/lua/vim/lsp/handlers.lua

@@ -437,7 +437,7 @@ function M.signature_help(_, result, ctx, config)
   local fbuf, fwin = util.open_floating_preview(lines, 'markdown', config)
   -- Highlight the active parameter.
   if hl then
-    vim.highlight.range(
+    vim.hl.range(
       fbuf,
       sig_help_ns,
       'LspSignatureActiveParameter',

runtime/lua/vim/lsp/semantic_tokens.lua

@@ -443,7 +443,7 @@ function STHighlighter:on_win(topline, botline)
         vim.api.nvim_buf_set_extmark(self.bufnr, state.namespace, token.line, token.start_col, {
           hl_group = hl_group,
           end_col = token.end_col,
-          priority = vim.highlight.priorities.semantic_tokens + delta,
+          priority = vim.hl.priorities.semantic_tokens + delta,
           strict = false,
         })
       end
@@ -723,7 +723,7 @@ end
 --- @inlinedoc
 ---
 --- Priority for the applied extmark.
---- (Default: `vim.highlight.priorities.semantic_tokens + 3`)
+--- (Default: `vim.hl.priorities.semantic_tokens + 3`)
 --- @field priority? integer
 
 --- Highlight a semantic token.
@@ -752,7 +752,7 @@ function M.highlight_token(token, bufnr, client_id, hl_group, opts)
   end
 
   opts = opts or {}
-  local priority = opts.priority or vim.highlight.priorities.semantic_tokens + 3
+  local priority = opts.priority or vim.hl.priorities.semantic_tokens + 3
 
   vim.api.nvim_buf_set_extmark(bufnr, state.namespace, token.line, token.start_col, {
     hl_group = hl_group,

runtime/lua/vim/lsp/util.lua

@@ -2,7 +2,6 @@ local protocol = require('vim.lsp.protocol')
 local validate = vim.validate
 local api = vim.api
 local list_extend = vim.list_extend
-local highlight = vim.highlight
 local uv = vim.uv
 
 local M = {}
@@ -1716,13 +1715,13 @@ do --[[ References ]]
         [protocol.DocumentHighlightKind.Write] = 'LspReferenceWrite',
       }
       local kind = reference['kind'] or protocol.DocumentHighlightKind.Text
-      highlight.range(
+      vim.hl.range(
         bufnr,
         reference_ns,
         document_highlight_kind[kind],
         { start_line, start_idx },
         { end_line, end_idx },
-        { priority = vim.highlight.priorities.user }
+        { priority = vim.hl.priorities.user }
       )
     end
   end

runtime/lua/vim/treesitter/highlighter.lua

@@ -328,7 +328,7 @@ local function on_line_impl(self, buf, line, is_spell_nav)
         -- The "priority" attribute can be set at the pattern level or on a particular capture
         local priority = (
           tonumber(metadata.priority or metadata[capture] and metadata[capture].priority)
-          or vim.highlight.priorities.treesitter
+          or vim.hl.priorities.treesitter
         ) + spell_pri_offset
 
         -- The "conceal" attribute can be set at the pattern level or on a particular capture

scripts/gen_vimdoc.lua

@@ -135,7 +135,7 @@ local config = {
   lua = {
     filename = 'lua.txt',
     section_order = {
-      'highlight.lua',
+      'hl.lua',
       'diff.lua',
       'mpack.lua',
       'json.lua',
@@ -174,7 +174,7 @@ local config = {
       'runtime/lua/vim/filetype.lua',
       'runtime/lua/vim/keymap.lua',
       'runtime/lua/vim/fs.lua',
-      'runtime/lua/vim/highlight.lua',
+      'runtime/lua/vim/hl.lua',
       'runtime/lua/vim/secure.lua',
       'runtime/lua/vim/version.lua',
       'runtime/lua/vim/_inspector.lua',
@@ -221,7 +221,7 @@ local config = {
       end
       if
         contains(name, {
-          'highlight',
+          'hl',
           'mpack',
           'json',
           'base64',

test/functional/lua/hl_spec.lua

@@ -9,7 +9,7 @@ local command = n.command
 local clear = n.clear
 local api = n.api
 
-describe('vim.highlight.range', function()
+describe('vim.hl.range', function()
   local screen
 
   before_each(function()
@@ -33,7 +33,7 @@ describe('vim.highlight.range', function()
   it('works with charwise selection', function()
     exec_lua(function()
       local ns = vim.api.nvim_create_namespace('')
-      vim.highlight.range(0, ns, 'Search', { 1, 5 }, { 3, 10 })
+      vim.hl.range(0, ns, 'Search', { 1, 5 }, { 3, 10 })
     end)
     screen:expect([[
       ^asdfghjkl{1:$}                                                  |
@@ -48,7 +48,7 @@ describe('vim.highlight.range', function()
   it('works with linewise selection', function()
     exec_lua(function()
       local ns = vim.api.nvim_create_namespace('')
-      vim.highlight.range(0, ns, 'Search', { 0, 0 }, { 4, 0 }, { regtype = 'V' })
+      vim.hl.range(0, ns, 'Search', { 0, 0 }, { 4, 0 }, { regtype = 'V' })
     end)
     screen:expect([[
       {10:^asdfghjkl}{100:$}                                                  |
@@ -63,7 +63,7 @@ describe('vim.highlight.range', function()
   it('works with blockwise selection', function()
     exec_lua(function()
       local ns = vim.api.nvim_create_namespace('')
-      vim.highlight.range(0, ns, 'Search', { 0, 0 }, { 4, 4 }, { regtype = '\022' })
+      vim.hl.range(0, ns, 'Search', { 0, 0 }, { 4, 4 }, { regtype = '\022' })
     end)
     screen:expect([[
       {10:^asdf}ghjkl{1:$}                                                  |
@@ -78,7 +78,7 @@ describe('vim.highlight.range', function()
   it('works with blockwise selection with width', function()
     exec_lua(function()
       local ns = vim.api.nvim_create_namespace('')
-      vim.highlight.range(0, ns, 'Search', { 0, 4 }, { 4, 7 }, { regtype = '\0226' })
+      vim.hl.range(0, ns, 'Search', { 0, 4 }, { 4, 7 }, { regtype = '\0226' })
     end)
     screen:expect([[
       ^asdf{10:ghjkl}{1:$}                                                  |
@@ -93,8 +93,8 @@ describe('vim.highlight.range', function()
   it('can use -1 or v:maxcol to indicate end of line', function()
     exec_lua(function()
       local ns = vim.api.nvim_create_namespace('')
-      vim.highlight.range(0, ns, 'Search', { 0, 4 }, { 1, -1 }, {})
+      vim.hl.range(0, ns, 'Search', { 0, 4 }, { 1, -1 }, {})
-      vim.highlight.range(0, ns, 'Search', { 2, 6 }, { 3, vim.v.maxcol }, {})
+      vim.hl.range(0, ns, 'Search', { 2, 6 }, { 3, vim.v.maxcol }, {})
     end)
     screen:expect([[
       ^asdf{10:ghjkl}{100:$}                                                  |
@@ -107,7 +107,7 @@ describe('vim.highlight.range', function()
   end)
 end)
 
-describe('vim.highlight.on_yank', function()
+describe('vim.hl.on_yank', function()
   before_each(function()
     clear()
   end)
@@ -115,7 +115,7 @@ describe('vim.highlight.on_yank', function()
   it('does not show errors even if buffer is wiped before timeout', function()
     command('new')
     exec_lua(function()
-      vim.highlight.on_yank({
+      vim.hl.on_yank({
         timeout = 10,
         on_macro = true,
         event = { operator = 'y', regtype = 'v' },
@@ -129,10 +129,10 @@ describe('vim.highlight.on_yank', function()
 
   it('does not close timer twice', function()
     exec_lua(function()
-      vim.highlight.on_yank({ timeout = 10, on_macro = true, event = { operator = 'y' } })
+      vim.hl.on_yank({ timeout = 10, on_macro = true, event = { operator = 'y' } })
       vim.uv.sleep(10)
       vim.schedule(function()
-        vim.highlight.on_yank({ timeout = 0, on_macro = true, event = { operator = 'y' } })
+        vim.hl.on_yank({ timeout = 0, on_macro = true, event = { operator = 'y' } })
       end)
     end)
     eq('', eval('v:errmsg'))
@@ -143,7 +143,7 @@ describe('vim.highlight.on_yank', function()
     exec_lua(function()
       vim.api.nvim_buf_set_mark(0, '[', 1, 1, {})
       vim.api.nvim_buf_set_mark(0, ']', 1, 1, {})
-      vim.highlight.on_yank({ timeout = math.huge, on_macro = true, event = { operator = 'y' } })
+      vim.hl.on_yank({ timeout = math.huge, on_macro = true, event = { operator = 'y' } })
     end)
     local ns = api.nvim_create_namespace('hlyank')
     local win = api.nvim_get_current_win()
@@ -157,7 +157,7 @@ describe('vim.highlight.on_yank', function()
     exec_lua(function()
       vim.api.nvim_buf_set_mark(0, '[', 1, 1, {})
       vim.api.nvim_buf_set_mark(0, ']', 1, 1, {})
-      vim.highlight.on_yank({ timeout = math.huge, on_macro = true, event = { operator = 'y' } })
+      vim.hl.on_yank({ timeout = math.huge, on_macro = true, event = { operator = 'y' } })
     end)
     local ns = api.nvim_create_namespace('hlyank')
     eq(api.nvim_get_current_win(), api.nvim__ns_get(ns).wins[1])
@@ -165,7 +165,7 @@ describe('vim.highlight.on_yank', function()
     exec_lua(function()
       vim.api.nvim_buf_set_mark(0, '[', 1, 1, {})
       vim.api.nvim_buf_set_mark(0, ']', 1, 1, {})
-      vim.highlight.on_yank({ timeout = math.huge, on_macro = true, event = { operator = 'y' } })
+      vim.hl.on_yank({ timeout = math.huge, on_macro = true, event = { operator = 'y' } })
     end)
     local win = api.nvim_get_current_win()
     eq({ win }, api.nvim__ns_get(ns).wins)