--- *mini.jump* Jump to next/previous single character --- --- MIT License Copyright (c) 2021 Evgeni Chasnovski, Adam Blažek --- Features: --- - Extend f, F, t, T to work on multiple lines. --- --- - Repeat jump by pressing f, F, t, T again. It is reset when cursor moved --- as a result of not jumping or timeout after idle time (duration --- customizable). --- --- - Highlight (after customizable delay) all possible target characters and --- stop it after some (customizable) idle time. --- --- - Normal, Visual, and Operator-pending (with dot-repeat as in clean Neovim) --- modes are supported. --- --- This module follows vim's |'ignorecase'| and |'smartcase'| options. When --- |'ignorecase'| is set, f, F, t, T will match case-insensitively. When --- |'smartcase'| is also set, f, F, t, T will only match lowercase --- characters case-insensitively. --- --- # Setup ~ --- --- This module needs a setup with `require('mini.jump').setup({})` --- (replace `{}` with your `config` table). It will create global Lua table --- `MiniJump` which you can use for scripting or manually (with --- `:lua MiniJump.*`). --- --- See |MiniJump.config| for `config` structure and default values. --- --- You can override runtime config settings locally to buffer inside --- `vim.b.minijump_config` which should have same structure as --- `MiniJump.config`. See |mini.nvim-buffer-local-config| for more details. --- --- To stop module from showing non-error feedback, set `config.silent = true`. --- --- # Highlight groups ~ --- *MiniJump-hl-groups* --- --- - `MiniJump` - all possible cursor positions. --- --- To change any highlight group, set it directly with |nvim_set_hl()|. --- --- # Disabling ~ --- --- To disable core functionality, set `vim.g.minijump_disable` (globally) or --- `vim.b.minijump_disable` (for a buffer) to `true`. Considering high number of --- different scenarios and customization intentions, writing exact rules for --- disabling module's functionality is left to user. See --- |mini.nvim-disabling-recipes| for common recipes. ---@tag MiniJump --- To allow user customization and integration of external tools, certain |User| --- autocommand events are triggered under common circumstances: --- --- - `MiniJumpGetTarget` - before asking user for the target. Use |MiniJump.state| --- for more information about the upcoming jump. --- - `MiniJumpStart` - after jumping has started. --- - `MiniJumpJump` - after performing a jump. --- - `MiniJumpStop` - after jumping is stopped. ---@tag MiniJump-events ---@alias __jump_target string|nil The string to jump to. ---@alias __jump_backward boolean|nil Whether to jump backward. ---@alias __jump_till boolean|nil Whether to jump just before/after the match instead of --- exactly on target. This includes positioning cursor past the end of --- previous/current line. Note that with backward jump this might lead to --- cursor being on target if can't be put past the line. ---@alias __jump_n_times number|nil Number of times to perform consecutive jumps. -- Module definition ========================================================== local MiniJump = {} local H = {} --- Module setup --- ---@param config table|nil Module config table. See |MiniJump.config|. --- ---@usage >lua --- require('mini.jump').setup() -- use default config --- -- OR --- require('mini.jump').setup({}) -- replace {} with your config table --- < MiniJump.setup = function(config) -- Export module _G.MiniJump = MiniJump -- Setup config config = H.setup_config(config) -- Apply config H.apply_config(config) -- Define behavior H.create_autocommands() -- Create default highlighting H.create_default_hl() end --- Defaults ~ ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section) MiniJump.config = { -- Module mappings. Use `''` (empty string) to disable one. mappings = { forward = 'f', backward = 'F', forward_till = 't', backward_till = 'T', repeat_jump = ';', }, -- Delay values (in ms) for different functionalities. Set any of them to -- a very big number (like 10^7) to virtually disable. delay = { -- Delay between jump and highlighting all possible jumps highlight = 250, -- Delay between jump and automatic stop if idle (no jump is done) idle_stop = 10000000, }, -- Whether to disable showing non-error feedback -- This also affects (purely informational) helper messages shown after -- idle time if user input is required. silent = false, } --minidoc_afterlines_end -- Module data ================================================================ --- Data about jumping state --- --- It stores various information used in this module. All elements, except --- `jumping`, is about the latest jump. They are used as default values for --- similar arguments. --- ---@usage This can be used to define mappings which depend on state; either as --- a standalone mapping or part of |MiniKeymap.map_multistep()|. For example: >lua --- --- -- Stop jumping after pressing `` --- local jump_stop = function() --- if not MiniJump.state.jumping then return '' end --- MiniJump.stop_jumping() --- end --- local opts = { expr = true, desc = 'Stop jumping' } --- vim.keymap.set({ 'n', 'x', 'o' }, '', jump_stop, opts) --- < ---@class JumpingState --- ---@field target __jump_target ---@field backward __jump_backward ---@field till __jump_till ---@field n_times __jump_n_times ---@field mode string Mode of latest jump (output of |mode()| with non-zero argument). ---@field jumping boolean Whether module is currently in "jumping mode": usage of --- |MiniJump.smart_jump()| and all mappings won't require target. ---@text --- Initial values: ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section) MiniJump.state = { target = nil, backward = false, till = false, n_times = 1, mode = nil, jumping = false, } --minidoc_afterlines_end -- Module functionality ======================================================= --- Jump to target --- --- Takes a string and jumps to its first occurrence in desired direction. --- --- All default values are taken from |MiniJump.state| to emulate latest jump. --- ---@param target __jump_target ---@param backward __jump_backward ---@param till __jump_till ---@param n_times __jump_n_times MiniJump.jump = function(target, backward, till, n_times) if H.is_disabled() then return end -- Dot-repeat should not change the state, so save it to later restore local expr_mode, is_dot_repeat = MiniJump._expr_mode, MiniJump._expr_mode ~= nil and not MiniJump._is_expr_init MiniJump._expr_mode, MiniJump._is_expr_init = nil, nil local state_snapshot = is_dot_repeat and vim.deepcopy(MiniJump.state) or nil -- Cache inputs for future use H.update_state(target, backward, till, n_times) if MiniJump.state.target == nil then return H.message('Can not jump because there is no recent `target`.') end -- Construct search and highlight pattern data local pattern, hl_pattern, flags = H.make_search_data() -- Delay highlighting after stopping previous one -- Update highlighting immediately if any highlighting is already present local config = H.get_config() H.timers.highlight:stop() local hl = vim.schedule_wrap(function() H.highlight(hl_pattern) end) H.timers.highlight:start(H.is_highlighting() and 0 or config.delay.highlight, 0, hl) -- Start idle timer after stopping previous one H.timers.idle_stop:stop() H.timers.idle_stop:start(config.delay.idle_stop, 0, vim.schedule_wrap(function() MiniJump.stop_jumping() end)) -- Force charwise selection in Operator-pending expression mapping if expr_mode ~= nil then vim.cmd('normal! ' .. expr_mode) end -- Make jump(s) H.cache.n_cursor_moved = 0 local was_jumping = MiniJump.state.jumping MiniJump.state.jumping = true if not was_jumping then H.trigger_event('MiniJumpStart') end H.trigger_event('MiniJumpJump') local has_jumped = false for _ = 1, MiniJump.state.n_times do local row = vim.fn.search(pattern, flags) has_jumped = has_jumped or row > 0 end -- Open enough folds to show jump if has_jumped then vim.cmd('normal! zv') end -- Track cursor position to account for movement not caught by `CursorMoved` H.cache.latest_cursor = H.get_cursor_data() -- Restore the state if needed. The jumping state is applied if there was jump -- or if it is possible to jump in other direction (i.e. target is present). MiniJump.state = is_dot_repeat and state_snapshot or MiniJump.state local search_pattern = '\\V' .. vim.fn.escape(MiniJump.state.target, '\\') MiniJump.state.jumping = has_jumped or vim.fn.search(search_pattern, 'wn') ~= 0 -- Nothing else to do if there was a jump if has_jumped then return end -- Ensure to stop jumping on next non-jump movement if MiniJump.state.jumping then H.cache.n_cursor_moved = H.cache.n_cursor_moved + 1 end -- When in Operator-pending mapping, disable selection to prevent a character -- from being consumed (due to selection of a cursor cell) if expr_mode ~= nil then vim.cmd('normal! ' .. expr_mode) end end --- Make smart jump --- --- If the last movement was a jump, perform another jump with the same target. --- Otherwise, wait for a target input (via |getcharstr()|). Respects |v:count|. --- --- All default values are taken from |MiniJump.state| to emulate latest jump. --- ---@param backward __jump_backward ---@param till __jump_till MiniJump.smart_jump = function(backward, till) if H.is_disabled() then return end -- Jumping should stop after mode change (use `mode(1)` to track 'omap' case) -- or if cursor has moved after latest jump local has_changed_mode = MiniJump.state.mode ~= vim.fn.mode(1) local has_changed_cursor = not vim.deep_equal(H.cache.latest_cursor, H.get_cursor_data()) if has_changed_mode or has_changed_cursor then MiniJump.stop_jumping() end H.update_state(nil, backward, till, vim.v.count1) -- Ask for target only when needed local target if not MiniJump.state.jumping or MiniJump.state.target == nil then target = H.get_target() -- Stop if user supplied invalid target if target == nil then return end end H.update_state(target) MiniJump.jump() end --- Stop jumping --- --- Removes highlights (if any) and forces the next smart jump to prompt for --- the target. Automatically called on appropriate Neovim |events|. MiniJump.stop_jumping = function() H.timers.highlight:stop() H.timers.idle_stop:stop() local was_jumping = MiniJump.state.jumping MiniJump.state.jumping = false H.cache.n_cursor_moved = 0 H.cache.latest_cursor = nil H.cache.msg_shown = false H.unhighlight() -- Trigger relevant event only if there was jumping if was_jumping then H.trigger_event('MiniJumpStop') end end -- Helper data ================================================================ -- Module default config H.default_config = vim.deepcopy(MiniJump.config) -- Cache for various operations H.cache = { -- Counter of number of CursorMoved events n_cursor_moved = 0, -- Latest cursor position data latest_cursor = nil, -- Whether helper message was shown msg_shown = false, } -- Timers for different delay-related functionalities H.timers = { highlight = vim.uv.new_timer(), idle_stop = vim.uv.new_timer() } -- Information about last match highlighting (stored *per window*): -- - Key: windows' unique buffer identifiers. -- - Value: table with: -- - `id` field for match id (from `vim.fn.matchadd()`). -- - `pattern` field for highlighted pattern. H.window_matches = {} -- Helper functionality ======================================================= -- Settings ------------------------------------------------------------------- H.setup_config = function(config) H.check_type('config', config, 'table', true) config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {}) H.check_type('delay', config.delay, 'table') H.check_type('delay.highlight', config.delay.highlight, 'number') H.check_type('delay.idle_stop', config.delay.idle_stop, 'number') H.check_type('mappings', config.mappings, 'table') H.check_type('mappings.forward', config.mappings.forward, 'string') H.check_type('mappings.backward', config.mappings.backward, 'string') H.check_type('mappings.forward_till', config.mappings.forward_till, 'string') H.check_type('mappings.backward_till', config.mappings.backward_till, 'string') H.check_type('mappings.repeat_jump', config.mappings.repeat_jump, 'string') H.check_type('silent', config.silent, 'boolean') return config end --stylua: ignore H.apply_config = function(config) MiniJump.config = config H.map('n', config.mappings.forward, 'lua MiniJump.smart_jump(false, false)', { desc = 'Jump forward' }) H.map('n', config.mappings.backward, 'lua MiniJump.smart_jump(true, false)', { desc = 'Jump backward' }) H.map('n', config.mappings.forward_till, 'lua MiniJump.smart_jump(false, true)', { desc = 'Jump forward till' }) H.map('n', config.mappings.backward_till, 'lua MiniJump.smart_jump(true, true)', { desc = 'Jump backward till' }) H.map('n', config.mappings.repeat_jump, 'lua MiniJump.jump()', { desc = 'Repeat jump' }) H.map('x', config.mappings.forward, 'lua MiniJump.smart_jump(false, false)', { desc = 'Jump forward' }) H.map('x', config.mappings.backward, 'lua MiniJump.smart_jump(true, false)', { desc = 'Jump backward' }) H.map('x', config.mappings.forward_till, 'lua MiniJump.smart_jump(false, true)', { desc = 'Jump forward till' }) H.map('x', config.mappings.backward_till, 'lua MiniJump.smart_jump(true, true)', { desc = 'Jump backward till' }) H.map('x', config.mappings.repeat_jump, 'lua MiniJump.jump()', { desc = 'Repeat jump' }) H.map('o', config.mappings.forward, H.make_expr_jump(false, false), { expr = true, desc = 'Jump forward' }) H.map('o', config.mappings.backward, H.make_expr_jump(true, false), { expr = true, desc = 'Jump backward' }) H.map('o', config.mappings.forward_till, H.make_expr_jump(false, true), { expr = true, desc = 'Jump forward till' }) H.map('o', config.mappings.backward_till, H.make_expr_jump(true, true), { expr = true, desc = 'Jump backward till' }) H.map('o', config.mappings.repeat_jump, H.make_expr_jump(), { expr = true, desc = 'Repeat jump' }) end H.create_autocommands = function() local gr = vim.api.nvim_create_augroup('MiniJump', {}) local au = function(event, pattern, callback, desc) vim.api.nvim_create_autocmd(event, { group = gr, pattern = pattern, callback = callback, desc = desc }) end au('CursorMoved', '*', H.on_cursormoved, 'On CursorMoved') -- Check current buffer not immediately to allow "temporary buffer switch" au({ 'BufLeave', 'InsertEnter' }, '*', vim.schedule_wrap(H.stop_if_curbuf), 'Stop jumping') au('ColorScheme', '*', H.create_default_hl, 'Ensure colors') end H.create_default_hl = function() vim.api.nvim_set_hl(0, 'MiniJump', { default = true, link = 'SpellRare' }) end H.is_disabled = function() return vim.g.minijump_disable == true or vim.b.minijump_disable == true end H.get_config = function(config) return vim.tbl_deep_extend('force', MiniJump.config, vim.b.minijump_config or {}, config or {}) end -- Mappings ------------------------------------------------------------------- H.make_expr_jump = function(backward, till) return function() if H.is_disabled() then return '' end local count = vim.v.count1 H.update_state(nil, backward, till, count) -- Ask for `target` for non-repeating jump as this will be used only in -- operator-pending mode. Dot-repeat is supported via expression-mapping. local isnt_repeat_jump = backward ~= nil and till ~= nil local target = isnt_repeat_jump and H.get_target() or nil if isnt_repeat_jump and target == nil then return '' end H.update_state(target) -- Set a flag to distinguish first call from dot-repeat MiniJump._is_expr_init = true -- Take into account forced Operator-pending modes ('nov', 'noV', 'no') local vis_mode = vim.fn.mode(1):match('^no(.+)$') or 'v' -- Encode state in expression for dot-repeat. Important to use `target=nil` -- for `repeat_jump` case to have it using latest jumping state during -- dot-repeat also (as does `nvim --clean`). local jump_cmd = string.format('MiniJump.jump(%s,%s,%s,%s)', vim.inspect(target), backward, till, count) local expr_mode_cmd = 'MiniJump._expr_mode = ' .. vim.inspect(vis_mode) return string.format('lua %s; %s', expr_mode_cmd, jump_cmd) end end -- Autocommands --------------------------------------------------------------- H.on_cursormoved = function() -- Check if jumping to avoid unnecessary actions on every CursorMoved if MiniJump.state.jumping then H.cache.n_cursor_moved = H.cache.n_cursor_moved + 1 -- Stop jumping only if `CursorMoved` was not a result of smart jump if H.cache.n_cursor_moved > 1 then MiniJump.stop_jumping() end end end H.stop_if_curbuf = function(ev) if ev.buf == vim.api.nvim_get_current_buf() then MiniJump.stop_jumping() end end -- Pattern matching ----------------------------------------------------------- H.make_search_data = function() local target = vim.fn.escape(MiniJump.state.target, [[\]]) local backward, till = MiniJump.state.backward, MiniJump.state.till local flags = backward and 'Wb' or 'W' local pattern, hl_pattern if till then -- General logic: moving pattern should match just before/after target, -- while highlight pattern should match target for every "movable" place. -- Also allow checking for "just before/after" across lines by accepting -- `\n` as possible match. if backward then -- NOTE: use `\@<=` instead of `\zs` because it behaves better in case of -- consecutive matches (like `xxxx` for target `x`) pattern = target .. [[\@<=\_.]] hl_pattern = target .. [[\ze\_.]] else pattern = [[\_.\ze]] .. target hl_pattern = [[\_.\@<=]] .. target end else local is_visual = vim.tbl_contains({ 'v', 'V', '\22' }, vim.fn.mode()) local is_exclusive = vim.o.selection == 'exclusive' if not backward and is_visual and is_exclusive then -- Still select target in case of exclusive visual selection pattern = target .. [[\zs\_.]] hl_pattern = target .. [[\ze\_.]] else pattern = target hl_pattern = target end end -- Enable 'very nomagic' mode and possibly case-insensitivity local ignore_case = vim.o.ignorecase and (not vim.o.smartcase or target == target:lower()) local prefix = ignore_case and [[\V\c]] or [[\V]] pattern, hl_pattern = prefix .. pattern, prefix .. hl_pattern return pattern, hl_pattern, flags end -- Highlighting --------------------------------------------------------------- H.highlight = function(pattern) if H.is_highlighting(pattern) or not MiniJump.state.jumping then return end -- Stop highlighting possible previous pattern. Needed to adjust highlighting -- when inside jumping but a different kind one. Example: first jump with -- `till = false` and then, without jumping stop, jump to same character with -- `till = true`. If this character is first on line, highlighting should change H.unhighlight() -- Never highlight in Insert mode if vim.fn.mode() == 'i' then return end local match_id = vim.fn.matchadd('MiniJump', pattern) H.window_matches[vim.api.nvim_get_current_win()] = { id = match_id, pattern = pattern } end H.unhighlight = function() -- Remove highlighting from all windows as jumping is intended to work only -- in current window. This will work also from other (usually popup) window. for win_id, match_info in pairs(H.window_matches) do if vim.api.nvim_win_is_valid(win_id) then -- Use `pcall` because there is an error if match id is not present. It -- can happen if something else called `clearmatches`. pcall(vim.fn.matchdelete, match_info.id, win_id) H.window_matches[win_id] = nil end end end ---@param pattern string|nil Highlight pattern to check for. If `nil`, checks for --- any highlighting registered in current window. ---@private H.is_highlighting = function(pattern) local win_id = vim.api.nvim_get_current_win() local match_info = H.window_matches[win_id] if match_info == nil then return false end return pattern == nil or match_info.pattern == pattern end -- Utilities ------------------------------------------------------------------ H.error = function(msg) error('(mini.jump) ' .. msg, 0) end H.check_type = function(name, val, ref, allow_nil) if type(val) == ref or (ref == 'callable' and vim.is_callable(val)) or (allow_nil and val == nil) then return end H.error(string.format('`%s` should be %s, not %s', name, ref, type(val))) end H.echo = function(msg, is_important) if H.get_config().silent then return end -- Construct message chunks msg = type(msg) == 'string' and { { msg } } or msg table.insert(msg, 1, { '(mini.jump) ', 'WarningMsg' }) -- Avoid hit-enter-prompt local chunks = msg if not is_important then chunks = {} local max_width = vim.o.columns * math.max(vim.o.cmdheight - 1, 0) + vim.v.echospace local tot_width = 0 for _, ch in ipairs(msg) do local new_ch = { vim.fn.strcharpart(ch[1], 0, max_width - tot_width), ch[2] } table.insert(chunks, new_ch) tot_width = tot_width + vim.fn.strdisplaywidth(new_ch[1]) if tot_width >= max_width then break end end end -- Echo. Force redraw to ensure that it is effective (`:h echo-redraw`) vim.cmd([[echo '' | redraw]]) vim.api.nvim_echo(chunks, is_important, {}) end H.message = function(msg) H.echo(msg, true) end H.trigger_event = function(event_name, data) vim.api.nvim_exec_autocmds('User', { pattern = event_name, data = data }) end H.update_state = function(target, backward, till, n_times) MiniJump.state.mode = vim.fn.mode(1) -- Don't use `? and <1> or <2>` because it doesn't work when `<1>` is `false` if target ~= nil then MiniJump.state.target = target end if backward ~= nil then MiniJump.state.backward = backward end if till ~= nil then MiniJump.state.till = till end if n_times ~= nil then MiniJump.state.n_times = n_times end end H.get_cursor_data = function() return { vim.api.nvim_get_current_win(), vim.api.nvim_win_get_cursor(0) } end H.get_target = function() local needs_reminder = true vim.defer_fn(function() if not needs_reminder then return end H.echo('Reminder to press a target single character ') H.cache.msg_shown = true end, 1000) H.trigger_event('MiniJumpGetTarget') local ok, char = pcall(vim.fn.getcharstr) needs_reminder = false if H.cache.msg_shown then vim.cmd('mode') end -- Terminate if couldn't get input (like with ) or on `` if not ok or char == '' or char == '\3' or char == '\27' then return nil end return char end H.map = function(mode, lhs, rhs, opts) if lhs == '' then return end opts = vim.tbl_deep_extend('force', { silent = true }, opts or {}) vim.keymap.set(mode, lhs, rhs, opts) end return MiniJump