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`)
-                       Priority for the applied extmark.
+                       `vim.hl.priorities.semantic_tokens + 3`) Priority for
+                       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.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
+                                                              *vim.hl.range()*
+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
-                     highlight
+                     `vim.hl.priorities.user`) Highlight priority
 
 
 ==============================================================================

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
---- (default: `vim.highlight.priorities.user`)
+--- Highlight priority
+--- (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