--- *mini.surround* Surround actions --- --- MIT License Copyright (c) 2021 Evgeni Chasnovski --- Fast and feature-rich surrounding. Can be configured to have experience --- similar to [tpope/vim-surround](https://github.com/tpope/vim-surround) --- (see |MiniSurround-vim-surround-config|). --- --- Features: --- - Actions (out of the box support for dot-repeat, |multicursor|, and |[count]|) --- with configurable mappings: --- - Add surrounding with `sa` (in visual mode or on motion). --- - Delete surrounding with `sd`. --- - Replace surrounding with `sr`. --- - Find surrounding with `sf` or `sF` (move cursor right or left). --- - Highlight surrounding with `sh`. --- --- - Surrounding is identified by a single character as both "input" (in --- `delete` and `replace` start, `find`, and `highlight`) and "output" (in --- `add` and `replace` end): --- - `f` - function call (string of alphanumeric symbols or `_` or `.` --- followed by balanced `()`). In "input" finds function call, in --- "output" prompts user to enter function name. --- - `t` - tag. In "input" finds tag with same identifier, in "output" --- prompts user to enter tag name with possible attributes. --- - All symbols in brackets `()`, `[]`, `{}`, `<>`. In "input" represents --- balanced brackets (open - with whitespace pad, close - without), in --- "output" - left and right parts of brackets. --- - `?` - interactive. Prompts user to enter left and right parts. --- - All other single character identifiers (supported by |getcharstr()|) --- represent surrounding with identical left and right parts. --- --- - Configurable search methods to find not only covering but possibly next, --- previous, or nearest surrounding. See more in |MiniSurround.config|. --- --- - All actions involving finding surrounding (delete, replace, find, --- highlight) can be used with suffix that changes search method to find --- previous/last. See more in |MiniSurround.config|. --- --- Known issues which won't be resolved: --- - Search for surrounding is done using Lua patterns (regex-like approach). --- So certain amount of false positives should be expected. --- --- - When searching for "input" surrounding, there is no distinction if it is --- inside string or comment. So in this case there will be not proper match --- for a function call: `f(a = ")", b = 1)`. --- --- - Tags are searched using regex-like methods, so issues are inevitable. --- Overall it is pretty good, but certain cases won't work. Like self-nested --- tags won't match correctly on both ends: ``. --- --- # Setup ~ --- --- This module needs a setup with `require('mini.surround').setup({})` --- (replace `{}` with your `config` table). It will create global Lua table --- `MiniSurround` which you can use for scripting or manually (with --- `:lua MiniSurround.*`). --- --- See |MiniSurround.config| for `config` structure and default values. --- --- You can override runtime config settings locally to buffer inside --- `vim.b.minisurround_config` which should have same structure as --- `MiniSurround.config`. See |mini.nvim-buffer-local-config| for more details. --- --- To stop module from showing non-error feedback, set `config.silent = true`. --- --- # Example usage ~ --- --- Regular mappings: --- - `saiw)` - add (`sa`) for inner word (`iw`) parenthesis (`)`). --- - `saiw?[[]]` - add (`sa`) for inner word (`iw`) interactive --- surrounding (`?`): `[[` for left and `]]` for right. --- - `2sdf` - delete (`sd`) second (`2`) surrounding function call (`f`). --- - `sr)tdiv` - replace (`sr`) surrounding parenthesis (`)`) with tag --- (`t`) with identifier `div` (`div` in command line prompt). --- - `sff` - find right (`sf`) part of surrounding function call (`f`). --- - `sh}` - highlight (`sh`) for a brief period of time surrounding curly --- brackets (`}`). --- --- Extended mappings (temporary force "prev"/"next" search methods): --- - `sdnf` - delete (`sd`) next (`n`) function call (`f`). --- - `srlf(` - replace (`sr`) last (`l`) function call (`f`) with padded --- bracket (`(`). --- - `2sfnt` - find (`sf`) second (`2`) next (`n`) tag (`t`). --- - `2shl}` - highlight (`sh`) last (`l`) second (`2`) curly bracket (`}`). --- --- # Comparisons ~ --- --- - [tpope/vim-surround](https://github.com/tpope/vim-surround): --- - `vim-surround` has completely different, with other focus set of --- default mappings, while |mini.surround| has a more coherent set. --- - |mini.surround| supports dot-repeat, customized search path (see --- |MiniSurround.config|), customized specifications (see --- |MiniSurround-surrounding-specification|) allowing usage of tree-sitter --- queries (see |MiniSurround.gen_spec.input.treesitter()|), --- highlighting and finding surrounding, "last"/"next" extended --- mappings. While `vim-surround` does not. --- - [machakann/vim-sandwich](https://github.com/machakann/vim-sandwich): --- - Both have same keybindings for common actions (add, delete, replace). --- - Otherwise same differences as with `tpope/vim-surround` (except --- dot-repeat because `vim-sandwich` supports it). --- - [kylechui/nvim-surround](https://github.com/kylechui/nvim-surround): --- - `nvim-surround` is designed after `tpope/vim-surround` with same --- default mappings and logic, while |mini.surround| has mappings --- similar to `machakann/vim-sandwich`. --- - |mini.surround| has more flexible customization of input surrounding --- (with composed patterns, region pair(s), search methods). --- - |mini.surround| supports |[count]| in both input and output --- surrounding (see |MiniSurround-count-with-actions|) while --- `nvim-surround` doesn't. --- - |mini.surround| supports "last"/"next" extended mappings. --- - |mini.ai|: --- - Both use similar logic for finding target: textobject in |mini.ai| --- and surrounding pair in |mini.surround|. While |mini.ai| uses --- extraction pattern for separate `a` and `i` textobjects, --- |mini.surround| uses it to select left and right surroundings --- (basically a difference between `a` and `i` textobjects). --- - Some builtin specifications are slightly different: --- - Quotes in |mini.ai| are balanced, in |mini.surround| they are not. --- - The |mini.surround| doesn't have argument surrounding. --- - Default behavior in |mini.ai| selects one of the edges into `a` --- textobject, while |mini.surround| - both. --- --- # Highlight groups ~ --- *MiniSurround-hl-groups* --- --- - `MiniSurround` - highlighting of requested surrounding. --- --- To change any highlight group, set it directly with |nvim_set_hl()|. --- --- # Disabling ~ --- --- To disable, set `vim.g.minisurround_disable` (globally) or --- `vim.b.minisurround_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 MiniSurround --- This table describes all builtin surroundings along with what they --- represent. Explanation: --- - `Key` represents the surrounding identifier: single character which should --- be typed after action mappings (see "Mappings" in |MiniSurround.config|). --- - `Name` is a description of surrounding. --- - `Example line` contains a string for which examples are constructed. The --- `*` denotes the cursor position over `a` character. --- - `Delete` shows the result of typing `sd` followed by surrounding identifier. --- It aims to demonstrate "input" surrounding which is also used in replace --- with `sr` (surrounding id is typed first), highlight with `sh`, find with --- `sf` and `sF`. --- - `Replace` shows the result of typing `sr!` followed by surrounding --- identifier (with possible follow up from user). It aims to demonstrate --- "output" surrounding which is also used in adding with `sa` (followed by --- textobject/motion or in Visual mode). --- --- Example: typing `sd)` with cursor on `*` (covers `a` character) changes line --- `!( *a (bb) )!` into `! aa (bb) !`. Typing `sr!)` changes same initial line --- into `(( aa (bb) ))`. --- > --- ┌───┬───────────────┬───────────────┬─────────────┬─────────────────┐ --- │Key│ Name │ Example line │ Delete │ Replace │ --- ├───┴───────────────┴───────────────┴─────────────┴─────────────────┤ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ ( │ Balanced () │ !( *a (bb) )! │ !aa (bb)! │ ( ( aa (bb) ) ) │ --- │ [ │ Balanced [] │ ![ *a [bb] ]! │ !aa [bb]! │ [ [ aa [bb] ] ] │ --- │ { │ Balanced {} │ !{ *a {bb} }! │ !aa {bb}! │ { { aa {bb} } } │ --- │ < │ Balanced <> │ !< *a >! │ !aa ! │ < < aa > > │ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ ) │ Balanced () │ !( *a (bb) )! │ ! aa (bb) ! │ (( aa (bb) )) │ --- │ ] │ Balanced [] │ ![ *a [bb] ]! │ ! aa [bb] ! │ [[ aa [bb] ]] │ --- │ } │ Balanced {} │ !{ *a {bb} }! │ ! aa {bb} ! │ {{ aa {bb} }} │ --- │ > │ Balanced <> │ !< *a >! │ ! aa ! │ << aa >> │ --- │ b │ Alias for │ !( *a {bb} )! │ ! aa {bb} ! │ (( aa {bb} )) │ --- │ │ ), ], or } │ │ │ │ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ q │ Alias for │ !'aa'*a'aa'! │ !'aaaaaa'! │ "'aa'aa'aa'" │ --- │ │ ", ', or ` │ │ │ │ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ ? │ User prompt │ !e * o! │ ! a ! │ ee a oo │ --- │ │(typed e and o)│ │ │ │ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ t │ Tag │ !*! │ !a! │ a │ --- │ │ │ │ │ (typed y) │ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ f │ Function call │ !f(*a, bb)! │ !aa, bb! │ g(f(*a, bb)) │ --- │ │ │ │ │ (typed g) │ --- ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ --- │ │ Default │ !_a*a_! │ !aaa! │ __aaa__ │ --- │ │ (typed _) │ │ │ │ --- └┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┘ --- < --- Notes: --- - All examples assume default `config.search_method`. --- - Open brackets differ from close brackets by how they treat inner edge --- whitespace: open includes it left and right parts, close does not. --- - Output value of `b` alias is same as `)`. For `q` alias - same as `"`. --- - Default surrounding is activated for all characters which are not --- configured surrounding identifiers. Notes: --- - Due to special handling of underlying `x.-x` Lua pattern --- (see |MiniSurround-search-algorithm|), it doesn't really support --- non-trivial `[count]` for "cover" search method. --- - When cursor is exactly on the identifier character while there are --- two matching candidates on both left and right, the one resulting in --- region with smaller width is preferred. ---@tag MiniSurround-builtin-surroundings --- Note: this is similar to |MiniAi-glossary|. --- --- REGION ~ --- Table representing region in a buffer. Fields: and for --- inclusive start and end positions ( might be `nil` to describe empty --- region). Each position is also a table with line and column --- (both start at 1). Examples: >lua --- --- { from = { line = 1, col = 1 }, to = { line = 2, col = 1 } } --- --- -- Empty region --- { from = { line = 10, col = 10 } } --- < --- REGION PAIR ~ --- Table representing regions for left and right surroundings. Fields: --- and with regions. Example: >lua --- --- { --- left = { from = { line = 1, col = 1 }, to = { line = 1, col = 1 } }, --- right = { from = { line = 1, col = 3 } }, --- } --- < --- PATTERN ~ --- String describing Lua pattern. --- --- SPAN ~ --- Interval inside a string (end-exclusive). Like [1, 5). Equal `from` and `to` edges --- describe empty span at that point. --- --- Span `A = [a1, a2)` covers `B = [b1, b2)` if every element of `B` is within --- `A` (`a1 <= b < a2`). It also is described as "B is nested inside A". --- --- NESTED PATTERN ~ --- Array of patterns aimed to describe nested spans. --- --- SPAN MATCHES NESTED PATTERN ~ --- If there is a sequence of consecutively nested spans each matching --- corresponding pattern within substring of previous span (or input string --- for first span). Example: >lua --- --- -- Nested patterns for balanced `()` with inner space --- { '%b()', '^. .* .$' } --- --- -- Example input string (with columns underneath for easier reading): --- "( ( () ( ) ) )" --- -- 12345678901234 --- < --- Here are all matching spans [1, 15) and [3, 13). Both [5, 7) and [8, 10) --- match first pattern but not second. All other combinations of `(` and `)` --- don't match first pattern (not balanced). --- --- COMPOSED PATTERN ~ --- Array with each element describing possible pattern (or array of them) at --- that place. Composed pattern basically defines all possible combinations of --- nested pattern (their cartesian product). Examples: --- --- 1. Either balanced `()` or balanced `[]` but both with inner edge space: >lua --- --- -- Composed pattern --- { { '%b()', '%b[]' }, '^. .* .$' } --- --- -- Composed pattern expanded into equivalent array of nested patterns --- { '%b()', '^. .* .$' } -- and --- { '%b[]', '^. .* .$' } --- < --- 2. Either "balanced `()` with inner edge space" or "balanced `[]` with no --- inner edge space", both with 5 or more characters: >lua --- --- -- Composed pattern --- { { { '%b()', '^. .* .$' }, { '%b[]', '^.[^ ].*[^ ].$' } }, '.....' } --- --- -- Composed pattern expanded into equivalent array of nested patterns --- { '%b()', '^. .* .$', '.....' } -- and --- { '%b[]', '^.[^ ].*[^ ].$', '.....' } --- < --- SPAN MATCHES COMPOSED PATTERN ~ --- If it matches at least one nested pattern from expanded composed pattern. ---@tag MiniSurround-glossary --- Surround specification is a table with keys: --- - - defines how to find and extract surrounding for "input" --- operations (like `delete`). See more in "Input surrounding" section. --- - - defines what to add on left and right for "output" operations --- (like `add`). See more in "Output surrounding" section. --- --- Example of surround info for builtin `)` identifier: >lua --- --- { --- input = { '%b()', '^.().*().$' }, --- output = { left = '(', right = ')' } --- } --- < --- # Input surrounding ~ --- --- Specification for input surrounding has a structure of composed pattern --- (see |MiniSurround-glossary|) with two differences: --- - Last pattern(s) should have two or four empty capture groups denoting --- how the last string should be processed to extract surrounding parts: --- - Two captures represent left part from start of string to first --- capture and right part - from second capture to end of string. --- Example: `a()b()c` defines left surrounding as `a`, right - `c`. --- - Four captures define left part inside captures 1 and 2, right part - --- inside captures 3 and 4. Example: `a()()b()c()` defines left part as --- empty, right part as `c`. --- - Allows callable objects (see |vim.is_callable()|) in certain places --- (enables more complex surroundings in exchange of increase in configuration --- complexity and computations): --- - If specification itself is a callable, it will be called without --- arguments and should return one of: --- - Composed pattern. Useful for implementing user input. Example of --- simplified variant of input surrounding for function call with --- name taken from user prompt: >lua --- --- function() --- local left_edge = vim.pesc(vim.fn.input('Function name: ')) --- return { left_edge .. '%b()', '^.-%(().*()%)$' } --- end --- < --- - Single region pair (see |MiniSurround-glossary|). Useful to allow --- full control over surrounding. Will be taken as is. Example of --- returning first and last lines of a buffer: >lua --- --- function() --- local n_lines = vim.fn.line('$') --- return { --- left = { --- from = { line = 1, col = 1 }, --- to = { line = 1, col = vim.fn.getline(1):len() } --- }, --- right = { --- from = { line = n_lines, col = 1 }, --- to = { line = n_lines, col = vim.fn.getline(n_lines):len() } --- }, --- } --- end --- < --- - Array of region pairs. Useful for incorporating other instruments, --- like treesitter (see |MiniSurround.gen_spec.input.treesitter()|). The --- best region pair will be picked in the same manner as with composed --- pattern (respecting options `n_lines`, `search_method`, etc.) using --- output region (from start of left region to end of right region). --- Example using edges of "best" line with display width more than 80: >lua --- --- function() --- local make_line_region_pair = function(n) --- local left = { line = n, col = 1 } --- local right = { line = n, col = vim.fn.getline(n):len() } --- return { --- left = { from = left, to = left }, --- right = { from = right, to = right }, --- } --- end --- --- local res = {} --- for i = 1, vim.fn.line('$') do --- if vim.fn.getline(i):len() > 80 then --- table.insert(res, make_line_region_pair(i)) --- end --- end --- return res --- end --- < --- - If there is a callable instead of assumed string pattern, it is expected --- to have signature `(line, init)` and behave like `pattern:find()`. --- It should return two numbers representing span in `line` next after --- or at `init` (`nil` if there is no such span). --- !IMPORTANT NOTE!: it means that output's `from` shouldn't be strictly --- to the left of `init` (it will lead to infinite loop). Not allowed as --- last item (as it should be pattern with captures). --- Example of matching only balanced parenthesis with big enough width: >lua --- --- { --- '%b()', --- function(s, init) --- if init > 1 or s:len() < 5 then return end --- return 1, s:len() --- end, --- '^.().*().$' --- } --- < --- More examples: >lua --- --- -- Pair of balanced brackets from set (used for builtin `b` identifier) --- { { '%b()', '%b[]', '%b{}' }, '^.().*().$' } --- --- -- Lua block string --- { '%[%[().-()%]%]' } --- < --- See |MiniSurround.gen_spec| for function wrappers to create commonly used --- surrounding specifications. --- --- # Output surrounding ~ --- --- Specification for output can be either a table with and fields, --- or a callable returning such table (will be called with no arguments). --- Strings can contain new lines character "\n" to add multiline parts. --- --- Examples: >lua --- --- -- Lua block string --- { left = '[[', right = ']]' } --- --- -- Brackets on separate lines (indentation is not preserved) --- { left = '(\n', right = '\n)' } --- --- -- Function call --- function() --- local function_name = MiniSurround.user_input('Function name') --- return { left = function_name .. '(', right = ')' } --- end --- < ---@tag MiniSurround-surrounding-specification --- |[count]| is supported by all actions in the following ways: --- --- - In add, two types of `[count]` is supported in Normal mode: --- `[count1]sa[count2][textobject]`. The `[count1]` defines how many times --- left and right parts of output surrounding will be repeated and `[count2]` is --- used for textobject. --- In Visual mode `[count]` is treated as `[count1]`. --- Example: `2sa3aw)` and `v3aw2sa)` will result into textobject `3aw` being --- surrounded by `((` and `))`. --- --- - In delete/replace/find/highlight `[count]` means "find n-th surrounding --- and execute operator on it". --- Example: `2sd)` on line `(a(b(c)b)a)` with cursor on `c` will result into --- `(ab(c)ba)` (and not in `(abcba)` if it would have meant "delete n times"). ---@tag MiniSurround-count-with-actions --- Search for the input surrounding relies on these principles: --- - Input surrounding specification is constructed based on surrounding --- identifier (see |MiniSurround-surrounding-specification|). --- - General search is done by converting some 2d buffer region (neighborhood --- of reference region) into 1d string (each line is appended with `\n`). --- Then search for a best span matching specification is done inside string --- (see |MiniSurround-glossary|). After that, span is converted back into 2d --- region. Note: first search is done inside reference region lines, and --- only after that - inside its neighborhood within `config.n_lines` (see --- |MiniSurround.config|). --- - The best matching span is chosen by iterating over all spans matching --- surrounding specification and comparing them with "current best". --- Comparison also depends on reference region (tighter covering is better, --- otherwise closer is better) and search method (if span is even considered). --- - Extract pair of spans (for left and right regions in region pair) based --- on extraction pattern (last item in nested pattern). --- - For |[count]| greater than 1, steps are repeated with current best match --- becoming reference region. One such additional step is also done if final --- region is equal to reference region. --- --- Notes: --- - Iteration over all matched spans is done in depth-first fashion with --- respect to nested pattern. --- - It is guaranteed that span is compared only once. --- - For the sake of increasing functionality, during iteration over all --- matching spans, some Lua patterns in composed pattern are handled --- specially. --- - `%bxx` (`xx` is two identical characters). It denotes balanced pair --- of identical characters and results into "paired" matches. For --- example, `%b""` for `"aa" "bb"` would match `"aa"` and `"bb"`, but --- not middle `" "`. --- - `x.-y` (`x` and `y` are different strings). It results only in matches with --- smallest width. For example, `e.-o` for `e e o o` will result only in --- middle `e o`. Note: it has some implications for when parts have --- quantifiers (like `+`, etc.), which usually can be resolved with --- frontier pattern `%f[]`. ---@tag MiniSurround-search-algorithm -- Module definition ========================================================== local MiniSurround = {} local H = {} --- Module setup --- ---@param config table|nil Module config table. See |MiniSurround.config|. --- ---@usage >lua --- require('mini.surround').setup() -- use default config --- -- OR --- require('mini.surround').setup({}) -- replace {} with your config table --- < MiniSurround.setup = function(config) -- Export module _G.MiniSurround = MiniSurround -- 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) ---@text # Mappings ~ --- --- `config.mappings` defines what mappings are set up for particular actions. --- By default it uses "prefix style" left hand side starting with "s" (for --- "surround"): `sa` - "surround add", `sd` - "surround delete", etc. --- --- Note: if any of the mappings start with "s" (as is by default), it is mapped --- to || to prevent accidental trigger of built-in |s| (can happen if there --- is a long enough delay between pressing "s" and the next key). Use `cl` instead. --- --- # Custom surroundings ~ --- --- User can define own surroundings by supplying `config.custom_surroundings`. --- It should be a table with keys being single character surrounding --- identifier (supported by |getcharstr()|) and values - surround specification --- (see |MiniSurround-surrounding-specification|). --- --- General recommendations: --- - In `config.custom_surroundings` only some data can be defined (like only --- `output`). Other fields will be taken from builtin surroundings. --- - Function returning surround info at or fields of --- specification is helpful when user input is needed (like asking for --- function name). Use |MiniSurround.user_input()| or |MiniInput.get()|. --- Return `nil` to stop any current surround operation. --- - Keys should use character representation which can be |getcharstr()| output. --- For example, `'\r'` and not `''`. --- --- Examples of using `config.custom_surroundings` (see more examples at --- |MiniSurround.gen_spec|): >lua --- --- local surround = require('mini.surround') --- surround.setup({ --- custom_surroundings = { --- -- Make `)` insert parts with spaces. `input` pattern stays the same. --- [')'] = { output = { left = '( ', right = ' )' } }, --- --- -- Use function to compute surrounding info --- ['*'] = { --- input = function() --- local n_star = MiniSurround.user_input('Number of * to find') --- local many_star = string.rep('%*', tonumber(n_star) or 1) --- return { many_star .. '().-()' .. many_star } --- end, --- output = function() --- local n_star = MiniSurround.user_input('Number of * to output') --- local many_star = string.rep('*', tonumber(n_star) or 1) --- return { left = many_star, right = many_star } --- end, --- }, --- }, --- }) --- --- -- Create custom surrounding for Lua's block string `[[...]]` --- -- Use this inside autocommand or 'after/ftplugin/lua.lua' file --- vim.b.minisurround_config = { --- custom_surroundings = { --- s = { --- input = { '%[%[().-()%]%]' }, --- output = { left = '[[', right = ']]' }, --- }, --- }, --- } --- < --- # Respect selection type ~ --- --- Boolean option `config.respect_selection_type` controls whether to respect --- selection type when adding and deleting surrounding. When enabled: --- - Linewise adding places surroundings on separate lines while indenting --- surrounded lines ones. --- - Deleting surroundings which look like they were the result of linewise --- adding will act to revert it: delete lines with surroundings and dedent --- surrounded lines ones. --- - Blockwise adding places surroundings on whole edges, not only start and --- end of selection. Note: it doesn't really work outside of text and in --- presence of multibyte characters; and probably won't due to --- implementation difficulties. --- --- # Search method ~ --- --- Value of `config.search_method` defines how best match search is done. --- Based on its value, one of the following matches will be selected: --- - Covering match. Left/right edge is before/after left/right edge of --- reference region. --- - Previous match. Left/right edge is before left/right edge of reference --- region. --- - Next match. Left/right edge is after left/right edge of reference region. --- - Nearest match. Whichever is closest among previous and next matches. --- --- Possible values are: --- - `'cover'` (default) - use only covering match. Don't use either previous or --- next; report that there is no surrounding found. --- - `'cover_or_next'` - use covering match. If not found, use next. --- - `'cover_or_prev'` - use covering match. If not found, use previous. --- - `'cover_or_nearest'` - use covering match. If not found, use nearest. --- - `'next'` - use next match. --- - `'previous'` - use previous match. --- - `'nearest'` - use nearest match. --- --- Note: search is first performed on the reference region lines and only --- after failure - on the whole neighborhood defined by `config.n_lines`. This --- means that with `config.search_method` not equal to `'cover'`, "previous" --- or "next" surrounding will end up as search result if they are found on --- first stage although covering match might be found in bigger, whole --- neighborhood. This design is based on observation that most of the time --- operation is done within reference region lines (usually cursor line). --- --- Here is an example of how replacing `)` with `]` surrounding is done based --- on a value of `'config.search_method'` when cursor is inside `bbb` word: --- - `'cover'`: `(a) bbb (c)` -> `(a) bbb (c)` (with message) --- - `'cover_or_next'`: `(a) bbb (c)` -> `(a) bbb [c]` --- - `'cover_or_prev'`: `(a) bbb (c)` -> `[a] bbb (c)` --- - `'cover_or_nearest'`: depends on cursor position. --- For first and second `b` - as in `cover_or_prev` (as previous match is --- nearer), for third - as in `cover_or_next` (as next match is nearer). --- - `'next'`: `(a) bbb (c)` -> `(a) bbb [c]`. Same outcome for `(bbb)`. --- - `'prev'`: `(a) bbb (c)` -> `[a] bbb (c)`. Same outcome for `(bbb)`. --- - `'nearest'`: depends on cursor position (same as in `'cover_or_nearest'`). --- --- # Search suffixes ~ --- --- To provide more searching possibilities, |mini.surround| creates extended --- mappings force "prev" and "next" methods for particular search. It does so --- by appending mapping with certain suffix: `config.mappings.suffix_last` for --- mappings which will use "prev" search method, `config.mappings.suffix_next` --- - "next" search method. --- --- Notes: --- - It creates new mappings only for actions involving surrounding search: --- delete, replace, find (right and left), highlight. --- - All new mappings behave the same way as if `config.search_method` is set --- to certain search method. They preserve dot-repeat support, respect |[count]|. --- - Supply empty string to disable creation of corresponding set of mappings. --- --- Example with default values (`n` for `suffix_next`, `l` for `suffix_last`) --- and initial line `(aa) (bb) (cc)`. --- - Typing `sdn)` with cursor inside `(aa)` results into `(aa) bb (cc)`. --- - Typing `sdl)` with cursor inside `(cc)` results into `(aa) bb (cc)`. --- - Typing `2srn)]` with cursor inside `(aa)` results into `(aa) (bb) [cc]`. --- --- # Setup similar to `tpope/vim-surround` ~ --- *MiniSurround-vim-surround-config* --- --- This module is primarily designed after `machakann/vim-sandwich`. To get --- behavior closest to `tpope/vim-surround` (but not identical), use this setup: >lua --- --- require('mini.surround').setup({ --- mappings = { --- add = 'ys', --- delete = 'ds', --- find = '', --- find_left = '', --- highlight = '', --- replace = 'cs', --- --- -- Add this only if you don't want to use extended mappings --- suffix_last = '', --- suffix_next = '', --- }, --- search_method = 'cover_or_next', --- }) --- --- -- Remap adding surrounding to Visual mode selection --- vim.keymap.del('x', 'ys') --- vim.keymap.set('x', 'S', [[:lua MiniSurround.add('visual')]], { silent = true }) --- --- -- Make special mapping for "add surrounding for line" --- vim.keymap.set('n', 'yss', 'ys_', { remap = true }) --- < MiniSurround.config = { -- Custom surroundings to be used on top of builtin ones. -- For more information with examples, see `:h MiniSurround.config`. custom_surroundings = {}, -- Duration (in ms) of highlight when calling `MiniSurround.highlight()` highlight_duration = 500, -- Module mappings. Use `''` (empty string) to disable one. mappings = { add = 'sa', -- Add surrounding in Normal and Visual modes delete = 'sd', -- Delete surrounding find = 'sf', -- Find surrounding (to the right) find_left = 'sF', -- Find surrounding (to the left) highlight = 'sh', -- Highlight surrounding replace = 'sr', -- Replace surrounding suffix_last = 'l', -- Suffix to search with "prev" method suffix_next = 'n', -- Suffix to search with "next" method }, -- Number of lines within which surrounding is searched n_lines = 20, -- Whether to respect selection type: -- - Place surroundings on separate lines in linewise mode. -- - Place surroundings on each line in blockwise mode. respect_selection_type = false, -- How to search for surrounding (first inside current line, then inside -- neighborhood). One of 'cover', 'cover_or_next', 'cover_or_prev', -- 'cover_or_nearest', 'next', 'prev', 'nearest'. For more details, -- see `:h MiniSurround.config`. search_method = 'cover', -- 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 functionality ======================================================= --- Add surrounding --- --- No need to use it directly, everything is setup in |MiniSurround.setup()|. --- ---@param mode string Mapping mode (normal by default). MiniSurround.add = function(mode) -- Needed to disable in visual mode if H.is_disabled() then return '' end -- Get marks' positions based on current mode local marks = H.get_marks_pos(mode) -- Always ask for user input for Visual mode action -- TODO: Adjust this for "semantic Visual dot-repeat" on Neovim>=0.13 if mode == 'visual' then H.cache = {} end -- Get surround info local surr_info = H.get_surround_spec('output') if surr_info == nil then return '' end -- Extend parts based on provided `[count]` before operator (if this is not -- from dot-repeat and was done already) if not surr_info.did_count then local count = H.cache.count or vim.v.count1 surr_info.left, surr_info.right = surr_info.left:rep(count), surr_info.right:rep(count) surr_info.did_count = true end -- Add surrounding. -- Possibly deal with linewise and blockwise addition separately local respect_selection_type = H.get_config().respect_selection_type if not respect_selection_type or marks.selection_type == 'charwise' then -- Begin insert from right to not break column numbers -- Insert after the right mark (`+ 1` is for that) H.region_replace({ from = { line = marks.second.line, col = marks.second.col + 1 } }, surr_info.right) H.region_replace({ from = marks.first }, surr_info.left) -- Set cursor to be on the right of left surrounding H.set_cursor(marks.first.line, marks.first.col + surr_info.left:len()) return end if marks.selection_type == 'linewise' then local from_line, to_line = marks.first.line, marks.second.line -- Save current range indent and indent surrounded lines local init_indent = H.get_range_indent(from_line, to_line) H.shift_indent('>', from_line, to_line) -- Put cursor on the start of first surrounded line H.set_cursor_nonblank(from_line) -- Put surroundings on separate lines vim.fn.append(to_line, init_indent .. surr_info.right) vim.fn.append(from_line - 1, init_indent .. surr_info.left) return end if marks.selection_type == 'blockwise' then -- NOTE: this doesn't work with mix of multibyte and normal characters, as -- well as outside of text lines. local from_col, to_col = marks.first.col, marks.second.col -- - Ensure that `to_col` is to the right of `from_col`. Can be not the -- case if visual block was selected from "south-west" to "north-east". from_col, to_col = math.min(from_col, to_col), math.max(from_col, to_col) for i = marks.first.line, marks.second.line do H.region_replace({ from = { line = i, col = to_col + 1 } }, surr_info.right) H.region_replace({ from = { line = i, col = from_col } }, surr_info.left) end H.set_cursor(marks.first.line, from_col + surr_info.left:len()) return end end --- Delete surrounding --- --- No need to use it directly, everything is setup in |MiniSurround.setup()|. MiniSurround.delete = function() -- Find input surrounding region local surr = H.find_surrounding(H.get_surround_spec('input')) if surr == nil then return '' end -- Delete surrounding region. Begin with right to not break column numbers. H.region_replace(surr.right, {}) H.region_replace(surr.left, {}) -- Set cursor to be on the right of deleted left surrounding local from = surr.left.from H.set_cursor(from.line, from.col) -- Possibly tweak deletion of linewise surrounding. Should act as reverse to -- linewise addition. if not H.get_config().respect_selection_type then return end local from_line, to_line = surr.left.from.line, surr.right.from.line local is_linewise_delete = from_line < to_line and H.is_line_blank(from_line) and H.is_line_blank(to_line) if is_linewise_delete then -- Dedent surrounded lines H.shift_indent('<', from_line, to_line) -- Place cursor on first surrounded line H.set_cursor_nonblank(from_line + 1) -- Delete blank lines left after deleting surroundings local buf_id = vim.api.nvim_get_current_buf() vim.fn.deletebufline(buf_id, to_line) vim.fn.deletebufline(buf_id, from_line) end end --- Replace surrounding --- --- No need to use it directly, everything is setup in |MiniSurround.setup()|. MiniSurround.replace = function() -- Find input surrounding region local surr = H.find_surrounding(H.get_surround_spec('input')) if surr == nil then return '' end -- Get output surround info local new_surr_info = H.get_surround_spec('output') if new_surr_info == nil then return '' end -- Replace by parts starting from right to not break column numbers H.region_replace(surr.right, new_surr_info.right) H.region_replace(surr.left, new_surr_info.left) -- Set cursor to be on the right of left surrounding local from = surr.left.from H.set_cursor(from.line, from.col + new_surr_info.left:len()) end --- Find surrounding --- --- No need to use it directly, everything is setup in |MiniSurround.setup()|. MiniSurround.find = function() -- Find surrounding region local surr = H.find_surrounding(H.get_surround_spec('input')) if surr == nil then return end -- Make array of unique positions to cycle through local pos_array = H.surr_to_pos_array(surr) -- Cycle cursor through positions and open enough folds vim.cmd("normal! m'") H.cursor_cycle(pos_array, H.cache.direction or 'right') vim.cmd('normal! zv') end --- Highlight surrounding --- --- No need to use it directly, everything is setup in |MiniSurround.setup()|. MiniSurround.highlight = function() -- Find surrounding region local surr = H.find_surrounding(H.get_surround_spec('input')) if surr == nil then return end -- Highlight surrounding region local config = H.get_config() local buf_id = vim.api.nvim_get_current_buf() H.region_highlight(buf_id, surr.left) H.region_highlight(buf_id, surr.right) vim.defer_fn(function() H.region_unhighlight(buf_id, surr.left) H.region_unhighlight(buf_id, surr.right) end, config.highlight_duration) end --- Update `MiniSurround.config.n_lines` from user input --- --- Mapping example: >lua --- --- vim.keymap.set('n', 'sn', 'lua MiniSurround.update_n_lines()') --- < MiniSurround.update_n_lines = function() local n_lines = MiniSurround.user_input('New number of neighbor lines', MiniSurround.config.n_lines) MiniSurround.config.n_lines = math.floor(tonumber(n_lines) or MiniSurround.config.n_lines) end --- Ask user for input --- --- This is mainly a wrapper for |input()| which allows empty string as input, --- cancelling with `` and ``, and slightly modifies prompt. Use it --- to ask for input inside function custom surrounding (see |MiniSurround.config|). MiniSurround.user_input = function(prompt, text) prompt = '(mini.surround) ' .. prompt if _G.MiniInput ~= nil then return MiniInput.get({ prompt = prompt, scope = 'cursor', init_keys = { text } }) end -- Major issue with both `vim.fn.input()` is that the only way to distinguish -- cancelling with `` and entering empty string with immediate `` is -- through `cancelreturn` option (see `:h input()`). In that case the return -- of `cancelreturn` will mean actual cancel, which removes possibility of -- using that string. Although doable with very obscure string, this is not -- very clean. -- Overcome this by adding temporary keystroke listener. local was_cancelled = false vim.on_key(function(key) was_cancelled = was_cancelled or key == '\27' or key == '\3' end, H.ns_id.input) -- Ask for input. Use `pcall` to allow `` to cancel user input -- NOTE: it would be GREAT to make this work with `vim.ui.input()` but I -- didn't find a way to make it work without major refactor of whole module. -- The main issue is that `vim.ui.input()` is designed to perform action in -- callback and current module design is to get output immediately. Although -- naive approach of -- `local res; vim.ui.input({...}, function(input) res = input end)` -- works in default `vim.ui.input`, its reimplementations can return from it -- immediately and proceed in main event loop. Couldn't find a relatively -- simple way to stop execution of this current function until `ui.input()`'s -- callback finished execution. vim.cmd('echohl Question') local ok, res = pcall(vim.fn.input, { prompt = prompt .. ': ', default = text or '' }) vim.cmd('echohl None | echo "" | redraw') vim.on_key(nil, H.ns_id.input) return (ok and not was_cancelled) and res or nil end --- Generate common surrounding specifications --- --- This is a table with two sets of generator functions: and --- (currently empty). Each is a table with function values generating --- corresponding surrounding specification. --- ---@seealso |MiniAi.gen_spec| MiniSurround.gen_spec = { input = {}, output = {} } --- Treesitter specification for input surrounding --- --- This is a specification in function form. When called with a pair of --- treesitter captures, it returns a specification function outputting an --- array of region pairs derived from and captures. It first --- searches for all matched nodes of outer capture and then completes each one --- with the biggest match of inner capture inside that node (if any). The result --- region pair is a difference between regions of outer and inner captures. --- --- In order for this to work, apart from working treesitter parser for desired --- language, user should have a reachable language-specific `'textobjects'` --- query (see |vim.treesitter.query.get()|). --- The most straightforward way for this is to have `textobjects.scm` query --- file with treesitter captures stored in some recognized path. This is --- primarily designed to be compatible with plugin --- `nvim-treesitter/nvim-treesitter-textobjects`, but can be used without it. --- --- Two most common approaches for having a query file: --- - Install `nvim-treesitter/nvim-treesitter-textobjects`. It has curated and --- well maintained builtin query files for many languages with a standardized --- capture names, like `call.outer`, `call.inner`, etc. --- - Manually create file `after/queries//textobjects.scm` in --- your |$XDG_CONFIG_HOME| directory. It should contain queries with --- captures (later used to define surrounding parts). See |lua-treesitter-query|. --- To verify that query file is reachable, run (example for "lua" language, --- output should have at least an intended file): >vim --- --- :lua print(vim.inspect(vim.treesitter.query.get_files('lua','textobjects'))) --- < --- Example configuration for function definition textobject with --- `nvim-treesitter/nvim-treesitter-textobjects` captures: >lua --- --- local ts_input = require('mini.surround').gen_spec.input.treesitter --- require('mini.surround').setup({ --- custom_surroundings = { --- -- Use tree-sitter to search for function call --- f = { --- input = ts_input({ outer = '@call.outer', inner = '@call.inner' }) --- }, --- } --- }) --- < --- Notes: --- - Be sure that query files don't contain unknown |treesitter-directives| --- (like `#make-range!`, for example). Otherwise surrounding with such captures --- might not be found as |lua-treesitter-core| won't treat them as captures. --- Verify with `:=vim.treesitter.query.get('lang', 'textobjects')` and see --- if the target capture is recognized as one. --- - It uses buffer's |filetype| to determine query language. --- - It first searches the language under cursor for matches. If no matches are --- found, it falls back to searching parent languages (up to the buffer's root --- language). If no matches are found again, it falls back to recursively --- searching all children languages (from the language under cursor). If no --- matches again - report no matches. --- - On large files it is slower than pattern-based textobjects. Still very --- fast though (one search should be magnitude of milliseconds or tens of --- milliseconds on really large file). --- ---@param captures table Captures for outer and inner parts of region pair: --- table with and fields with captures for outer --- (`[left.form; right.to]`) and inner (`(left.to; right.from)` both edges --- exclusive, i.e. they won't be a part of surrounding) regions. Each value --- should be a string capture starting with `'@'`. ---@param opts table|nil Options. Not used at the moment. --- ---@return function Function which returns array of current buffer region pairs --- representing differences between outer and inner captures. --- ---@seealso - |MiniSurround-surrounding-specification| for how this type of --- surrounding specification is processed. --- - |vim.treesitter.query.get()| for how query is fetched. --- - |Query:iter_captures()| for how all query captures are iterated in case of --- no `nvim-treesitter`. --- - |MiniAi.gen_spec.treesitter()| for similar |mini.ai| generator. MiniSurround.gen_spec.input.treesitter = function(captures, opts) -- TODO: Remove after releasing 'mini.nvim' 0.19.0 opts = opts or {} if opts.use_nvim_treesitter then vim.notify( '(mini.surround) `opts.use_nvim_treesitter` in `MiniSurround.gen_spec.input.treesitter()` is deprecated.' .. " It will be removed after the next 'mini.nvim' release in favor of using built-in `vim.treesitter` API." .. ' Drop setting this option.' .. ' In case of problems not addressed in `:h MiniSurround.gen_spec.input.treesitter()`, please open an issue.', vim.log.levels.WARN ) end captures = H.prepare_captures(captures) -- Tree-sitter ranges are 0-based, end-exclusive, and usually -- `row1-col1-byte1-row2-col2-byte2` (i.e. "range six") format. local ts_range_to_region = function(r) -- The `master` branch of 'nvim-treesitter' can return "range four" format -- if it uses custom directives, like `#make-range!`. Due to the fact that -- it doesn't fully mock the `TSNode:range()` method to return "range six". -- TODO: Remove after 'nvim-treesitter' `master` branch support is dropped. local offset = #r == 4 and -1 or 0 local res = { from = { line = r[1] + 1, col = r[2] + 1 }, to = { line = r[4 + offset] + 1, col = r[5 + offset] } } -- NOTE: Adjust "row-exclusive, col-0" range that means "all previous row -- including the newline character" if res.to.col == 0 then res.to.line = res.to.line - 1 res.to.col = vim.fn.col({ res.to.line, '$' }) end return res end return function() local has_nvim_treesitter = pcall(require, 'nvim-treesitter') and pcall(require, 'nvim-treesitter.query') local range_pair_querier = (has_nvim_treesitter and opts.use_nvim_treesitter) and H.get_matched_range_pairs_plugin or H.get_matched_range_pairs_builtin local matched_range_pairs = range_pair_querier(captures) -- Return array of region pairs return vim.tbl_map(function(range_pair) local outer_region = ts_range_to_region(range_pair.outer) local left_from, right_to = outer_region.from, outer_region.to local left_to, right_from if range_pair.inner == nil then left_to = right_to right_from = H.pos_to_right(right_to) right_to = nil else local inner_region = ts_range_to_region(range_pair.inner) left_to, right_from = inner_region.from, inner_region.to -- Take into account that inner capture should be both edges exclusive left_to, right_from = H.pos_to_left(left_to), H.pos_to_right(right_from) end return { left = { from = left_from, to = left_to }, right = { from = right_from, to = right_to } } end, matched_range_pairs) end end -- Helper data ================================================================ -- Module default config H.default_config = vim.deepcopy(MiniSurround.config) -- Namespaces to be used within module H.ns_id = { highlight = vim.api.nvim_create_namespace('MiniSurroundHighlight'), input = vim.api.nvim_create_namespace('MiniSurroundInput'), } --stylua: ignore -- Builtin surroundings H.builtin_surroundings = { -- Use balanced pair for brackets. Use opening ones to possibly -- replace/delete innder edge whitespace. ['('] = { input = { '%b()', '^.%s*().-()%s*.$' }, output = { left = '( ', right = ' )' } }, [')'] = { input = { '%b()', '^.().*().$' }, output = { left = '(', right = ')' } }, ['['] = { input = { '%b[]', '^.%s*().-()%s*.$' }, output = { left = '[ ', right = ' ]' } }, [']'] = { input = { '%b[]', '^.().*().$' }, output = { left = '[', right = ']' } }, ['{'] = { input = { '%b{}', '^.%s*().-()%s*.$' }, output = { left = '{ ', right = ' }' } }, ['}'] = { input = { '%b{}', '^.().*().$' }, output = { left = '{', right = '}' } }, ['<'] = { input = { '%b<>', '^.%s*().-()%s*.$' }, output = { left = '< ', right = ' >' } }, ['>'] = { input = { '%b<>', '^.().*().$' }, output = { left = '<', right = '>' } }, -- Derived from user prompt ['?'] = { input = function() local left = MiniSurround.user_input('Left surrounding') if left == nil or left == '' then return end local right = MiniSurround.user_input('Right surrounding') if right == nil or right == '' then return end return { vim.pesc(left) .. '().-()' .. vim.pesc(right) } end, output = function() local left = MiniSurround.user_input('Left surrounding') if left == nil then return end local right = MiniSurround.user_input('Right surrounding') if right == nil then return end return { left = left, right = right } end, }, -- Brackets ['b'] = { input = { { '%b()', '%b[]', '%b{}' }, '^.().*().$' }, output = { left = '(', right = ')' } }, -- Function call ['f'] = { input = { '%f[%w_%.][%w_%.]+%b()', '^.-%(().*()%)$' }, output = function() local fun_name = MiniSurround.user_input('Function name') if fun_name == nil then return nil end return { left = ('%s('):format(fun_name), right = ')' } end, }, -- Tag ['t'] = { input = { '<(%w-)%f[^<%w][^<>]->.-', '^<.->().*()$' }, output = function() local tag_full = MiniSurround.user_input('Tag') if tag_full == nil then return nil end local tag_name = tag_full:match('^%S*') return { left = '<' .. tag_full .. '>', right = '' } end, }, -- Quotes ['q'] = { input = { { "'.-'", '".-"', '`.-`' }, '^.().*().$' }, output = { left = '"', right = '"' } }, } -- Cache for dot-repeatability. This table is currently used with these keys: -- - 'input' - surround info for searching (in 'delete' and 'replace' start). -- - 'output' - surround info for adding (in 'add' and 'replace' end). -- - 'direction' - direction in which `MiniSurround.find()` should go. -- Currently is not used for dot-repeat, but for easier mappings. -- - 'search_method' - search method. -- - 'msg_shown' - whether helper message was shown. H.cache = {} -- 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('custom_surroundings', config.custom_surroundings, 'table') H.check_type('highlight_duration', config.highlight_duration, 'number') H.check_type('mappings', config.mappings, 'table') H.check_type('n_lines', config.n_lines, 'number') H.check_type('respect_selection_type', config.respect_selection_type, 'boolean') H.validate_search_method(config.search_method) H.check_type('silent', config.silent, 'boolean') H.check_type('mappings.add', config.mappings.add, 'string') H.check_type('mappings.delete', config.mappings.delete, 'string') H.check_type('mappings.find', config.mappings.find, 'string') H.check_type('mappings.find_left', config.mappings.find_left, 'string') H.check_type('mappings.highlight', config.mappings.highlight, 'string') H.check_type('mappings.replace', config.mappings.replace, 'string') H.check_type('mappings.suffix_last', config.mappings.suffix_last, 'string') H.check_type('mappings.suffix_next', config.mappings.suffix_next, 'string') return config end --stylua: ignore H.apply_config = function(config) MiniSurround.config = config local maps, maps_l, maps_n = config.mappings, {}, {} local suf_l, suf_n = maps.suffix_last, maps.suffix_next for k, v in pairs(maps) do -- Don't create extended mapping if user chose not to create a regular one maps_l[k] = (v ~= '' and suf_l ~= '') and (v .. suf_l) or '' maps_n[k] = (v ~= '' and suf_n ~= '') and (v .. suf_n) or '' end local m = function(mode, lhs, rhs, desc) H.map(mode, lhs, rhs, { expr = true, desc = desc }) end m('n', maps.add, H.make_operator('add', nil, true), 'Add surrounding') H.map('x', maps.add, ':lua MiniSurround.add("visual")', { desc = 'Add surrounding to selection' }) m('n', maps.delete, H.make_operator('delete', nil), 'Delete surrounding') m('n', maps_l.delete, H.make_operator('delete', 'prev'), 'Delete previous surrounding') m('n', maps_n.delete, H.make_operator('delete', 'next'), 'Delete next surrounding') m('n', maps.replace, H.make_operator('replace', nil), 'Replace surrounding') m('n', maps_l.replace, H.make_operator('replace', 'prev'), 'Replace previous surrounding') m('n', maps_n.replace, H.make_operator('replace', 'next'), 'Replace next surrounding') m('n', maps.find, H.make_action('find', 'right', nil), 'Find right surrounding') m('x', maps.find, H.make_action('find', 'right', nil), 'Find right surrounding') m('o', maps.find, H.make_action('find', 'right', nil), 'Find right surrounding') m('n', maps_l.find, H.make_action('find', 'right', 'prev'), 'Find previous right surrounding') m('x', maps_l.find, H.make_action('find', 'right', 'prev'), 'Find previous right surrounding') m('o', maps_l.find, H.make_action('find', 'right', 'prev'), 'Find previous right surrounding') m('n', maps_n.find, H.make_action('find', 'right', 'next'), 'Find next right surrounding') m('x', maps_n.find, H.make_action('find', 'right', 'next'), 'Find next right surrounding') m('o', maps_n.find, H.make_action('find', 'right', 'next'), 'Find next right surrounding') m('n', maps.find_left, H.make_action('find', 'left', nil), 'Find left surrounding') m('x', maps.find_left, H.make_action('find', 'left', nil), 'Find left surrounding') m('o', maps.find_left, H.make_action('find', 'left', nil), 'Find left surrounding') m('n', maps_l.find_left, H.make_action('find', 'left', 'prev'), 'Find previous left surrounding') m('x', maps_l.find_left, H.make_action('find', 'left', 'prev'), 'Find previous left surrounding') m('o', maps_l.find_left, H.make_action('find', 'left', 'prev'), 'Find previous left surrounding') m('n', maps_n.find_left, H.make_action('find', 'left', 'next'), 'Find next left surrounding') m('x', maps_n.find_left, H.make_action('find', 'left', 'next'), 'Find next left surrounding') m('o', maps_n.find_left, H.make_action('find', 'left', 'next'), 'Find next left surrounding') m('n', maps.highlight, H.make_action('highlight', nil, nil), 'Highlight surrounding') m('n', maps_l.highlight, H.make_action('highlight', nil, 'prev'), 'Highlight previous surrounding') m('n', maps_n.highlight, H.make_action('highlight', nil, 'next'), 'Highlight next surrounding') end H.create_autocommands = function() local gr = vim.api.nvim_create_augroup('MiniSurround', {}) vim.api.nvim_create_autocmd('ColorScheme', { group = gr, callback = H.create_default_hl, desc = 'Ensure colors' }) end H.create_default_hl = function() vim.api.nvim_set_hl(0, 'MiniSurround', { default = true, link = 'IncSearch' }) end H.is_disabled = function() return vim.g.minisurround_disable == true or vim.b.minisurround_disable == true end H.get_config = function(config) return vim.tbl_deep_extend('force', MiniSurround.config, vim.b.minisurround_config or {}, config or {}) end H.validate_search_method = function(x) local allowed_methods = vim.tbl_keys(H.span_compare_methods) if vim.tbl_contains(allowed_methods, x) then return end table.sort(allowed_methods) local allowed_methods_string = table.concat(vim.tbl_map(vim.inspect, allowed_methods), ', ') H.error('`search_method` should be one of ' .. allowed_methods_string) end -- Mappings ------------------------------------------------------------------- H.make_operator = function(task, search_method, ask_for_textobject) return function() if H.is_disabled() then -- Using `` helps to stop moving cursor caused by current -- implementation detail of adding `' '` inside expression mapping return [[\]] end H.cache = { count = vim.v.count1, search_method = search_method } vim.o.operatorfunc = 'v:lua.MiniSurround.' .. task -- NOTEs: -- - Prepend with command to reset `vim.v.count1` to allow -- `[count1]sa[count2][textobject]`. -- - Concatenate `' '` to operator output to "disable" motion -- required by `g@`. It is used to enable dot-repeatability. return 'redrawg@' .. (ask_for_textobject and '' or ' ') end end H.make_action = function(task, direction, search_method) return function() if H.is_disabled() then return '' end H.cache = { count = vim.v.count1, direction = direction, search_method = search_method } return 'lua MiniSurround.' .. task .. '()' end end -- Work with surrounding info ------------------------------------------------- H.is_mc_cascade = function() return vim.v.cascading end if vim.fn.has('nvim-0.13') == 0 then H.is_mc_cascade = function() return false end end H.get_surround_spec = function(surr_type) -- Should ask for user input if a result of initial user mapping AND during -- its multicursor cascade (as it will replay all keys). -- BUT should NOT ask for input later as a result of `.`, even during -- multicursor cascade (as it will replay `.`). H.cache.n_calls = H.cache.n_calls or { input = 0, output = 0 } if not H.is_mc_cascade() then H.cache.n_calls[surr_type] = H.cache.n_calls[surr_type] + 1 end if H.cache.n_calls[surr_type] <= 1 then H.cache[surr_type] = nil end -- Try using cache if H.cache[surr_type] ~= nil then return H.cache[surr_type] end -- Prompt user to enter identifier of surrounding local char = H.user_surround_id(surr_type) if char == nil then return nil end -- Prefer surrounding specification: custom > built-in > default local res = (H.get_config().custom_surroundings[char] or {})[surr_type] if res == nil then res = (H.builtin_surroundings[char] or {})[surr_type] end if res == nil then res = H.get_default_surrounding(char, surr_type) end -- - NOTE: Make sure that in-place modifications don't affect the source res = vim.deepcopy(res) -- Allow function returning spec or surrounding region(s) if vim.is_callable(res) then res = res() end -- Do nothing if supplied not appropriate structure if not H.is_surrounding_info(res, surr_type) then return nil end -- Wrap callable tables to be an actual functions. Otherwise they might be -- confused with list of patterns. if H.is_composed_pattern(res) then res = vim.tbl_map(H.wrap_callable_table, res) end -- Track id for possible messages. Use metatable to pass "islist" check. res = setmetatable(res, { __index = { id = char } }) -- Cache result H.cache[surr_type] = res return res end H.get_default_surrounding = function(char, surr_type) return surr_type == 'output' and { left = char, right = char } or { vim.pesc(char) .. '().-()' .. vim.pesc(char) } end H.is_surrounding_info = function(x, surr_type) if surr_type == 'input' then return H.is_composed_pattern(x) or H.is_region_pair(x) or H.is_region_pair_array(x) elseif surr_type == 'output' then return (type(x) == 'table' and type(x.left) == 'string' and type(x.right) == 'string') end end H.is_region = function(x) if type(x) ~= 'table' then return false end local from_is_valid = type(x.from) == 'table' and type(x.from.line) == 'number' and type(x.from.col) == 'number' -- Allow `to` to be `nil` to describe empty regions local to_is_valid = true if x.to ~= nil then to_is_valid = type(x.to) == 'table' and type(x.to.line) == 'number' and type(x.to.col) == 'number' end return from_is_valid and to_is_valid end H.is_region_pair = function(x) if type(x) ~= 'table' then return false end return H.is_region(x.left) and H.is_region(x.right) end H.is_region_pair_array = function(x) if not vim.islist(x) then return false end for _, v in ipairs(x) do if not H.is_region_pair(v) then return false end end return true end H.is_composed_pattern = function(x) if not (vim.islist(x) and #x > 0) then return false end for _, val in ipairs(x) do local val_type = type(val) if not (val_type == 'table' or val_type == 'string' or vim.is_callable(val)) then return false end end return true end -- Work with finding surrounding ---------------------------------------------- ---@param surr_spec table Composed pattern. Last item(s) - extraction template. ---@private H.find_surrounding = function(surr_spec) if surr_spec == nil then return end if H.is_region_pair(surr_spec) then return surr_spec end local config = H.get_config() local cur_pos = vim.api.nvim_win_get_cursor(0) local opts = { n_lines = config.n_lines, n_times = H.cache.count or vim.v.count1, -- Empty region at cursor position. This won't get called in Visual mode, -- so don't check for it (to return visual selection, as in 'mini.ai'). reference_region = { from = { line = cur_pos[1], col = cur_pos[2] + 1 } }, search_method = H.cache.search_method or config.search_method, } H.validate_search_method(opts.search_method) local region_pair = H.find_surrounding_region_pair(surr_spec, opts) if region_pair == nil then local msg = ([[No surrounding %s found within %d line%s and `config.search_method = '%s'`.]]):format( vim.inspect((opts.n_times > 1 and opts.n_times or '') .. surr_spec.id), opts.n_lines, opts.n_lines > 1 and 's' or '', opts.search_method ) H.message(msg) end return region_pair end H.find_surrounding_region_pair = function(surr_spec, opts) local reference_region, n_times, n_lines = opts.reference_region, opts.n_times, opts.n_lines if n_times == 0 then return end -- Find `n_times` matching spans evolving from reference region span -- First try to find inside 0-neighborhood local neigh = H.get_neighborhood(reference_region, 0) local reference_span = neigh.region_to_span(reference_region) local find_next = function(cur_reference_span) local res = H.find_best_match(neigh, surr_spec, cur_reference_span, opts) -- If didn't find in 0-neighborhood, possibly try extend one if res.span == nil then -- Stop if no need to extend neighborhood if n_lines == 0 or neigh.n_neighbors > 0 then return {} end -- Update data with respect to new neighborhood local cur_reference_region = neigh.span_to_region(cur_reference_span) neigh = H.get_neighborhood(reference_region, n_lines) reference_span = neigh.region_to_span(reference_region) cur_reference_span = neigh.region_to_span(cur_reference_region) -- Recompute based on new neighborhood res = H.find_best_match(neigh, surr_spec, cur_reference_span, opts) end return res end local find_res = { span = reference_span } for _ = 1, n_times do find_res = find_next(find_res.span) if find_res.span == nil then return end end -- Extract final span local extract = function(span, extract_pattern) -- Use table extract pattern to allow array of regions as surrounding spec -- Pair of spans is constructed based on best region pair if type(extract_pattern) == 'table' then return extract_pattern end -- First extract local (with respect to best matched span) surrounding spans local s = neigh['1d']:sub(span.from, span.to - 1) local local_surr_spans = H.extract_surr_spans(s, extract_pattern) -- Convert local spans to global local off = span.from - 1 local left, right = local_surr_spans.left, local_surr_spans.right return { left = { from = left.from + off, to = left.to + off }, right = { from = right.from + off, to = right.to + off }, } end local final_spans = extract(find_res.span, find_res.extract_pattern) local outer_span = { from = final_spans.left.from, to = final_spans.right.to } -- Ensure that output region is different from reference. if H.is_span_covering(reference_span, outer_span) then find_res = find_next(find_res.span) if find_res.span == nil then return end final_spans = extract(find_res.span, find_res.extract_pattern) outer_span = { from = final_spans.left.from, to = final_spans.right.to } if H.is_span_covering(reference_span, outer_span) then return end end -- Convert to region pair return { left = neigh.span_to_region(final_spans.left), right = neigh.span_to_region(final_spans.right) } end -- Work with treesitter surrounding ------------------------------------------- H.prepare_captures = function(captures) local is_capture = function(x) return type(x) == 'string' and x:sub(1, 1) == '@' end if not (type(captures) == 'table' and is_capture(captures.outer) and is_capture(captures.inner)) then H.error('Wrong format for `captures`. See `MiniSurround.gen_spec.input.treesitter()` for details.') end return { outer = captures.outer, inner = captures.inner } end H.get_matched_range_pairs_plugin = function(captures) local ts_queries = require('nvim-treesitter.query') local buf_id = vim.api.nvim_get_current_buf() local outer_matches = ts_queries.get_capture_matches_recursively(buf_id, captures.outer, 'textobjects') -- Make sure that found matches contain `node` field that is actually a node, -- otherwise later `get_capture_matches` will error as it requires an actual -- `TSNode` object. This is needed as capture might be defined with custom -- directive (like `#make-range!`) which 'nvim-treesitter' handles manually -- by returning "extended range" and not `TSNode`. outer_matches = vim.tbl_filter(function(x) return x.node.tree ~= nil end, outer_matches) -- Pick inner range as the biggest range for node matching inner query. This -- is needed because query output is not guaranteed to come in order, so just -- picking first one is not enough. return vim.tbl_map(function(m_outer) local outer_range = vim.treesitter.get_range(m_outer.node, buf_id, m_outer.metadata) local inner = ts_queries.get_capture_matches(0, captures.inner, 'textobjects', m_outer.node, nil) local inner_ranges = vim.tbl_map(function(m) return vim.treesitter.get_range(m.node, buf_id, m.metadata) end, inner) return { outer = outer_range, inner = H.get_biggest_nested_range(inner_ranges, outer_range) } end, outer_matches) end H.get_matched_range_pairs_builtin = function(captures) -- Get buffer's parser (LanguageTree) local buf_id = vim.api.nvim_get_current_buf() -- TODO: Remove `opts.error` after compatibility with Neovim=0.11 is dropped local has_parser, parser = pcall(vim.treesitter.get_parser, buf_id, nil, { error = false }) if not has_parser or parser == nil then H.error_treesitter('parser') end -- Get parser (LanguageTree) at cursor (important for injected languages) local pos = vim.api.nvim_win_get_cursor(0) local lang_tree = parser:language_for_range({ pos[1] - 1, pos[2], pos[1] - 1, pos[2] }) local init_lang_tree = lang_tree local missing_query_langs = {} -- Compute matched ranges for both outer and inner captures local outer, inner = {}, {} -- Go up parent trees to work with injected languages while (vim.tbl_isempty(inner) or vim.tbl_isempty(outer)) and lang_tree ~= nil do H.append_lang_ranges(outer, inner, missing_query_langs, buf_id, captures, lang_tree) lang_tree = lang_tree:parent() end -- Fall back to children trees for injected languages if vim.tbl_isempty(inner) or vim.tbl_isempty(outer) then local check_children check_children = function(l_tree) for _, child in pairs(l_tree:children()) do H.append_lang_ranges(outer, inner, missing_query_langs, buf_id, captures, child) check_children(child) end end check_children(init_lang_tree) end -- Match outer and inner ranges: for each outer range pick the biggest inner -- range that lies within outer local res = {} for i, o in ipairs(outer) do res[i] = { outer = o, inner = H.get_biggest_nested_range(inner, o) } end if vim.tbl_isempty(res) and not vim.tbl_isempty(missing_query_langs) then H.error_treesitter('query', vim.tbl_keys(missing_query_langs)) end return res end H.append_lang_ranges = function(outer, inner, missing_query_langs, buf_id, captures, lang_tree) local lang = lang_tree:lang() local query = vim.treesitter.query.get(lang, 'textobjects') if query ~= nil then H.append_ranges(outer, inner, buf_id, query, captures, lang_tree) end if query == nil then missing_query_langs[lang] = true end end H.append_ranges = function(outer, inner, buf_id, query, captures, lang_tree) for _, tree in ipairs(lang_tree:trees()) do local root = tree:root() vim.list_extend(outer, H.get_match_ranges_builtin(root, buf_id, query, captures.outer:sub(2))) vim.list_extend(inner, H.get_match_ranges_builtin(root, buf_id, query, captures.inner:sub(2))) end end H.get_match_ranges_builtin = function(root, buf_id, query, capture) local res = {} -- TODO: Remove `opts.all` after compatibility with Neovim=0.10 is dropped for _, match, metadata in query:iter_matches(root, buf_id, nil, nil, { all = true }) do for capture_id, nodes in pairs(match) do local mt = metadata[capture_id] if query.captures[capture_id] == capture then table.insert(res, H.get_nodes_range_builtin(nodes, buf_id, mt)) end end end return res end H.get_nodes_range_builtin = function(nodes, buf_id, metadata) -- Get matched range as spanning from left most node start to right most node -- end. This accounts for several matched nodes that are intentionally there -- to cover complex cases. Approach is named "quantified captures". local left, right for _, node in ipairs(nodes) do local range = vim.treesitter.get_range(node, buf_id, metadata) if left == nil or range[3] < left[3] then left = range end if right == nil or range[6] > right[6] then right = range end end return { left[1], left[2], left[3], right[4], right[5], right[6] } end H.get_biggest_nested_range = function(ranges, parent) local best_range, best_byte_count = nil, -math.huge for _, r in ipairs(ranges) do local is_nested = parent[3] <= r[3] and r[6] <= parent[6] and not (parent[3] == r[3] and r[6] == parent[6]) local byte_count = r[6] - r[3] + 1 if is_nested and best_byte_count < byte_count then best_range, best_byte_count = r, byte_count end end return best_range end H.error_treesitter = function(failed_get, langs) local buf_id, ft = vim.api.nvim_get_current_buf(), vim.bo.filetype if langs == nil then local has_lang, ft_lang = pcall(vim.treesitter.language.get_lang, ft) -- `vim.treesitter.language.get_lang()` defaults to `ft` on Neovim>0.11 -- TODO: Drop check after compatibility with Neovim=0.10 is dropped langs = (has_lang and ft_lang ~= nil) and { ft_lang } or { ft } end table.sort(langs) local langs_str = table.concat(vim.tbl_map(vim.inspect, langs), ', ') local langs_noun = #langs == 1 and 'language' or 'languages' local msg = string.format('Can not get %s for buffer %d and %s %s.', failed_get, buf_id, langs_noun, langs_str) H.error(msg) end -- Work with matching spans --------------------------------------------------- ---@param neighborhood table Output of `get_neighborhood()`. ---@param surr_spec table ---@param reference_span table Span to cover. ---@param opts table Fields: . ---@private H.find_best_match = function(neighborhood, surr_spec, reference_span, opts) local best_span, best_nested_pattern, current_nested_pattern local f = function(span) if H.is_better_span(span, best_span, reference_span, opts) then best_span = span best_nested_pattern = current_nested_pattern end end if H.is_region_pair_array(surr_spec) then -- Iterate over all spans representing outer regions in array for _, region_pair in ipairs(surr_spec) do -- Construct outer region used to find best region pair local outer_region = { from = region_pair.left.from, to = region_pair.right.to or region_pair.right.from } -- Consider outer region only if it is completely within neighborhood if neighborhood.is_region_inside(outer_region) then -- Make future extract pattern based directly on region pair current_nested_pattern = { { left = neighborhood.region_to_span(region_pair.left), right = neighborhood.region_to_span(region_pair.right), }, } f(neighborhood.region_to_span(outer_region)) end end else -- Iterate over all matched spans for _, nested_pattern in ipairs(H.cartesian_product(surr_spec)) do current_nested_pattern = nested_pattern H.iterate_matched_spans(neighborhood['1d'], nested_pattern, f) end end local extract_pattern if best_nested_pattern ~= nil then extract_pattern = best_nested_pattern[#best_nested_pattern] end return { span = best_span, extract_pattern = extract_pattern } end H.iterate_matched_spans = function(line, nested_pattern, f) local max_level = #nested_pattern -- Keep track of visited spans to ensure only one call of `f`. -- Example: `((a) (b))`, `{'%b()', '%b()'}` local visited = {} local process process = function(level, level_line, level_offset) local pattern = nested_pattern[level] local next_span = function(s, init) return H.string_find(s, pattern, init) end if vim.is_callable(pattern) then next_span = pattern end local is_same_balanced = type(pattern) == 'string' and pattern:match('^%%b(.)%1$') ~= nil local init = 1 while init <= level_line:len() do local from, to = next_span(level_line, init) if from == nil then break end if level == max_level then local found_match = H.new_span(from + level_offset, to + level_offset) local found_match_id = string.format('%s_%s', found_match.from, found_match.to) if not visited[found_match_id] then f(found_match) visited[found_match_id] = true end else local next_level_line = level_line:sub(from, to) local next_level_offset = level_offset + from - 1 process(level + 1, next_level_line, next_level_offset) end -- Start searching from right end to implement "balanced" pair. -- This doesn't work with regular balanced pattern because it doesn't -- capture nested brackets. init = (is_same_balanced and to or from) + 1 end end process(1, line, 0) end -- NOTE: spans are end-exclusive to allow empty spans via `from == to` H.new_span = function(from, to) return { from = from, to = to == nil and from or (to + 1) } end ---@param candidate table Candidate span to test against `current`. ---@param current table|nil Current best span. ---@param reference table Reference span to cover. ---@param opts table Fields: . ---@private H.is_better_span = function(candidate, current, reference, opts) -- Candidate should be never equal or nested inside reference if H.is_span_covering(reference, candidate) or H.is_span_equal(candidate, reference) then return false end return H.span_compare_methods[opts.search_method](candidate, current, reference) end H.span_compare_methods = { cover = function(candidate, current, reference) local res = H.is_better_covering_span(candidate, current, reference) if res ~= nil then return res end -- If both are not covering, `candidate` is not better (as it must cover) return false end, cover_or_next = function(candidate, current, reference) local res = H.is_better_covering_span(candidate, current, reference) if res ~= nil then return res end -- If not covering, `candidate` must be "next" and closer to reference if not H.is_span_on_left(reference, candidate) then return false end if current == nil then return true end local dist = H.span_distance.next return dist(candidate, reference) < dist(current, reference) end, cover_or_prev = function(candidate, current, reference) local res = H.is_better_covering_span(candidate, current, reference) if res ~= nil then return res end -- If not covering, `candidate` must be "previous" and closer to reference if not H.is_span_on_left(candidate, reference) then return false end if current == nil then return true end local dist = H.span_distance.prev return dist(candidate, reference) < dist(current, reference) end, cover_or_nearest = function(candidate, current, reference) local res = H.is_better_covering_span(candidate, current, reference) if res ~= nil then return res end -- If not covering, `candidate` must be closer to reference if current == nil then return true end local dist = H.span_distance.near return dist(candidate, reference) < dist(current, reference) end, next = function(candidate, current, reference) if H.is_span_covering(candidate, reference) then return false end -- `candidate` must be "next" and closer to reference if not H.is_span_on_left(reference, candidate) then return false end if current == nil then return true end local dist = H.span_distance.next return dist(candidate, reference) < dist(current, reference) end, prev = function(candidate, current, reference) if H.is_span_covering(candidate, reference) then return false end -- `candidate` must be "previous" and closer to reference if not H.is_span_on_left(candidate, reference) then return false end if current == nil then return true end local dist = H.span_distance.prev return dist(candidate, reference) < dist(current, reference) end, nearest = function(candidate, current, reference) if H.is_span_covering(candidate, reference) then return false end -- `candidate` must be closer to reference if current == nil then return true end local dist = H.span_distance.near return dist(candidate, reference) < dist(current, reference) end, } H.span_distance = { -- Other possible choices of distance between [a1, a2] and [b1, b2]: -- - Hausdorff distance: max(|a1 - b1|, |a2 - b2|). -- Source: -- https://math.stackexchange.com/questions/41269/distance-between-two-ranges -- - Minimum distance: min(|a1 - b1|, |a2 - b2|). -- Distance is chosen so that "next span" in certain direction is the closest next = function(span_1, span_2) return math.abs(span_1.from - span_2.from) end, prev = function(span_1, span_2) return math.abs(span_1.to - span_2.to) end, near = function(span_1, span_2) return math.min(math.abs(span_1.from - span_2.from), math.abs(span_1.to - span_2.to)) end, } H.is_better_covering_span = function(candidate, current, reference) local candidate_is_covering = H.is_span_covering(candidate, reference) local current_is_covering = H.is_span_covering(current, reference) if candidate_is_covering and current_is_covering then -- Covering candidate is better than covering current if it is narrower return (candidate.to - candidate.from) < (current.to - current.from) end if candidate_is_covering and not current_is_covering then return true end if not candidate_is_covering and current_is_covering then return false end -- Return `nil` if neither span is covering return nil end --stylua: ignore H.is_span_covering = function(span, span_to_cover) if span == nil or span_to_cover == nil then return false end if span.from == span.to then return (span.from == span_to_cover.from) and (span_to_cover.to == span.to) end if span_to_cover.from == span_to_cover.to then return (span.from <= span_to_cover.from) and (span_to_cover.to < span.to) end return (span.from <= span_to_cover.from) and (span_to_cover.to <= span.to) end H.is_span_equal = function(span_1, span_2) if span_1 == nil or span_2 == nil then return false end return (span_1.from == span_2.from) and (span_1.to == span_2.to) end H.is_span_on_left = function(span_1, span_2) if span_1 == nil or span_2 == nil then return false end return (span_1.from <= span_2.from) and (span_1.to <= span_2.to) end H.is_point_inside_spans = function(point, spans) for _, span in ipairs(spans) do if span[1] <= point and point <= span[2] then return true end end return false end H.str_utfindex = function(s, i) return vim.str_utfindex(s, 'utf-32', i) end if vim.fn.has('nvim-0.11') == 0 then H.str_utfindex = function(s, i) return (vim.str_utfindex(s, i)) end end H.str_byteindex = function(s, i) return vim.str_byteindex(s, 'utf-32', i) end if vim.fn.has('nvim-0.11') == 0 then H.str_byteindex = function(s, i) return vim.str_byteindex(s, i) end end -- Work with operator marks --------------------------------------------------- H.get_marks_pos = function(mode) -- Region is inclusive on both ends local mark1, mark2 if mode == 'visual' then mark1, mark2 = '<', '>' else mark1, mark2 = '[', ']' end local pos1 = vim.api.nvim_buf_get_mark(0, mark1) local pos2 = vim.api.nvim_buf_get_mark(0, mark2) local selection_type = H.get_selection_type(mode) -- Tweak position in linewise mode as marks are placed on the first column if selection_type == 'linewise' then -- Move start mark past the indent local _, line1_indent = vim.fn.getline(pos1[1]):find('^%s*') pos1[2] = line1_indent -- Move end mark to the last non-whitespace character pos2[2] = vim.fn.getline(pos2[1]):find('%s*$') - 2 end -- Make columns 1-based instead of 0-based. This is needed because -- `nvim_buf_get_mark()` returns the first 0-based byte of mark symbol and -- all the following operations are done with Lua's 1-based indexing. pos1[2], pos2[2] = pos1[2] + 1, pos2[2] + 1 -- Tweak second position to respect multibyte characters. Reasoning: -- - These positions will be used with `region_replace()` to add some text, -- which operates on byte columns. -- - For the first mark we want the first byte of symbol, then text will be -- insert to the left of the mark. -- - For the second mark we want last byte of symbol. To add surrounding to -- the right, use `pos2[2] + 1`. if mode == 'visual' and vim.o.selection == 'exclusive' then -- Respect 'selection' option pos2[2] = pos2[2] - 1 else local line2 = vim.fn.getline(pos2[1]) -- Use `math.min()` because it might lead to 'index out of range' error -- when mark is positioned at the end of line (that extra space which is -- selected when selecting with `v$`) local utf_index = H.str_utfindex(line2, math.min(#line2, pos2[2])) -- This returns the last byte inside character because `vim.str_byteindex()` -- 'rounds upwards to the end of that sequence'. pos2[2] = H.str_byteindex(line2, utf_index) end return { first = { line = pos1[1], col = pos1[2] }, second = { line = pos2[1], col = pos2[2] }, selection_type = selection_type, } end H.get_selection_type = function(mode) if (mode == 'char') or (mode == 'visual' and vim.fn.visualmode() == 'v') then return 'charwise' end if (mode == 'line') or (mode == 'visual' and vim.fn.visualmode() == 'V') then return 'linewise' end if (mode == 'block') or (mode == 'visual' and vim.fn.visualmode() == '\22') then return 'blockwise' end end -- Work with cursor ----------------------------------------------------------- H.set_cursor = function(line, col) vim.api.nvim_win_set_cursor(0, { line, col - 1 }) end H.set_cursor_nonblank = function(line) H.set_cursor(line, 1) vim.cmd('normal! ^') end H.compare_pos = function(pos1, pos2) if pos1.line < pos2.line then return '<' end if pos1.line > pos2.line then return '>' end if pos1.col < pos2.col then return '<' end if pos1.col > pos2.col then return '>' end return '=' end H.cursor_cycle = function(pos_array, dir) local cur_pos = vim.api.nvim_win_get_cursor(0) cur_pos = { line = cur_pos[1], col = cur_pos[2] + 1 } local compare, to_left, to_right, res_pos -- NOTE: `pos_array` should be an increasingly ordered array of positions for _, pos in pairs(pos_array) do compare = H.compare_pos(cur_pos, pos) -- Take position when moving to left if cursor is strictly on right. -- This will lead to updating `res_pos` until the rightmost such position. to_left = compare == '>' and dir == 'left' -- Take position when moving to right if cursor is strictly on left. -- This will update result only once leading to the leftmost such position. to_right = res_pos == nil and compare == '<' and dir == 'right' if to_left or to_right then res_pos = pos end end res_pos = res_pos or (dir == 'right' and pos_array[1] or pos_array[#pos_array]) H.set_cursor(res_pos.line, res_pos.col) end -- Work with user input ------------------------------------------------------- H.user_surround_id = function(surr_type) -- Get from user single character surrounding identifier local needs_reminder = true vim.defer_fn(function() if not needs_reminder then return end local msg = string.format('Reminder to press %s surrounding id ', surr_type) H.echo(msg) H.cache.msg_shown = true end, 1000) 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 -- Work with positions -------------------------------------------------------- H.pos_to_left = function(pos) if pos.line == 1 and pos.col == 1 then return { line = pos.line, col = pos.col } end if pos.col == 1 then return { line = pos.line - 1, col = H.get_line_cols(pos.line - 1) } end return { line = pos.line, col = pos.col - 1 } end H.pos_to_right = function(pos) local n_cols = H.get_line_cols(pos.line) -- Using `>` and not `>=` helps with removing '\n' and in the last line if pos.line == vim.api.nvim_buf_line_count(0) and pos.col > n_cols then return { line = pos.line, col = n_cols } end if pos.col > n_cols then return { line = pos.line + 1, col = 1 } end return { line = pos.line, col = pos.col + 1 } end -- Work with regions ---------------------------------------------------------- H.region_replace = function(region, text) -- Compute start and end position for `vim.api.nvim_buf_set_text()`. -- Indexing is zero-based. Rows - end-inclusive, columns - end-exclusive. local start_row, start_col = region.from.line - 1, region.from.col - 1 local end_row, end_col -- Allow empty region if H.region_is_empty(region) then end_row, end_col = start_row, start_col else end_row, end_col = region.to.line - 1, region.to.col -- Possibly correct to allow removing new line character if end_row < vim.api.nvim_buf_line_count(0) and H.get_line_cols(end_row + 1) < end_col then end_row, end_col = end_row + 1, 0 end end -- Allow single string as replacement if type(text) == 'string' then text = { text } end -- Allow `\n` in string to denote new lines if #text > 0 then text = vim.split(table.concat(text, '\n'), '\n') end -- Replace. Use `pcall()` to do nothing if some position is out of bounds. pcall(vim.api.nvim_buf_set_text, 0, start_row, start_col, end_row, end_col, text) end H.surr_to_pos_array = function(surr) local res = {} local append_position = function(pos, correction_direction) if pos == nil then return end -- Don't go past the line if it is not empty if H.get_line_cols(pos.line) < pos.col and pos.col > 1 then pos = correction_direction == 'left' and H.pos_to_left(pos) or H.pos_to_right(pos) end -- Don't add duplicate. Assumes that positions are used increasingly. local line, col = pos.line, pos.col local last = res[#res] if not (last ~= nil and last.line == line and last.col == col) then table.insert(res, { line = line, col = col }) end end -- Possibly correct position towards inside of surrounding region -- Also don't add positions from empty regions if not H.region_is_empty(surr.left) then append_position(surr.left.from, 'right') append_position(surr.left.to, 'right') end if not H.region_is_empty(surr.right) then append_position(surr.right.from, 'left') append_position(surr.right.to, 'left') end return res end H.region_highlight = function(buf_id, region) -- Don't highlight empty region if H.region_is_empty(region) then return end local ns_id = H.ns_id.highlight -- Indexing is zero-based. Rows - end-inclusive, columns - end-exclusive. local from_line, from_col, to_line, to_col = region.from.line - 1, region.from.col - 1, region.to.line - 1, region.to.col H.highlight_range(buf_id, ns_id, 'MiniSurround', { from_line, from_col }, { to_line, to_col }) end H.region_unhighlight = function(buf_id, region) local ns_id = H.ns_id.highlight -- Remove highlights from whole lines as it is the best available granularity vim.api.nvim_buf_clear_namespace(buf_id, ns_id, region.from.line - 1, (region.to or region.from).line) end H.region_is_empty = function(region) return region.to == nil end -- Work with text ------------------------------------------------------------- H.get_range_indent = function(from_line, to_line) local n_indent, indent = math.huge, nil local lines = vim.api.nvim_buf_get_lines(0, from_line - 1, to_line, true) local n_indent_cur, indent_cur for _, l in ipairs(lines) do _, n_indent_cur, indent_cur = l:find('^(%s*)') -- Don't indent blank lines if n_indent_cur < n_indent and n_indent_cur < l:len() then n_indent, indent = n_indent_cur, indent_cur end end return indent or '' end H.shift_indent = function(command, from_line, to_line) if to_line < from_line then return end vim.cmd('silent ' .. from_line .. ',' .. to_line .. command) end H.is_line_blank = function(line_num) return vim.fn.nextnonblank(line_num) ~= line_num end -- Work with Lua patterns ----------------------------------------------------- H.extract_surr_spans = function(s, extract_pattern) local positions = { s:match(extract_pattern) } local is_all_numbers = true for _, pos in ipairs(positions) do if type(pos) ~= 'number' then is_all_numbers = false end end local is_valid_positions = is_all_numbers and (#positions == 2 or #positions == 4) if not is_valid_positions then local msg = 'Could not extract proper positions (two or four empty captures) from ' .. string.format([[string '%s' with extraction pattern '%s'.]], s, extract_pattern) H.error(msg) end if #positions == 2 then return { left = H.new_span(1, positions[1] - 1), right = H.new_span(positions[2], s:len()) } end return { left = H.new_span(positions[1], positions[2] - 1), right = H.new_span(positions[3], positions[4] - 1) } end -- Work with cursor neighborhood ---------------------------------------------- ---@param reference_region table Reference region. ---@param n_neighbors number Maximum number of neighbors to include before --- start line and after end line. ---@private H.get_neighborhood = function(reference_region, n_neighbors) -- Compute '2d neighborhood' of (possibly empty) region local from_line, to_line = reference_region.from.line, (reference_region.to or reference_region.from).line local line_start = math.max(1, from_line - n_neighbors) local line_end = math.min(vim.api.nvim_buf_line_count(0), to_line + n_neighbors) local neigh2d = vim.api.nvim_buf_get_lines(0, line_start - 1, line_end, false) -- Append 'newline' character to distinguish between lines in 1d case for k, v in pairs(neigh2d) do neigh2d[k] = v .. '\n' end -- '1d neighborhood': position is determined by offset from start local neigh1d = table.concat(neigh2d, '') -- Convert 2d buffer position to 1d offset local pos_to_offset = function(pos) if pos == nil then return nil end local line_num = line_start local offset = 0 while line_num < pos.line do offset = offset + neigh2d[line_num - line_start + 1]:len() line_num = line_num + 1 end return offset + pos.col end -- Convert 1d offset to 2d buffer position local offset_to_pos = function(offset) if offset == nil then return nil end local line_num = 1 local line_offset = 0 while line_num <= #neigh2d and line_offset + neigh2d[line_num]:len() < offset do line_offset = line_offset + neigh2d[line_num]:len() line_num = line_num + 1 end return { line = line_start + line_num - 1, col = offset - line_offset } end -- Convert 2d region to 1d span local region_to_span = function(region) if region == nil then return nil end local is_empty = region.to == nil local to = region.to or region.from return { from = pos_to_offset(region.from), to = pos_to_offset(to) + (is_empty and 0 or 1) } end -- Convert 1d span to 2d region local span_to_region = function(span) if span == nil then return nil end -- NOTE: this might lead to outside of line positions due to added `\n` at -- the end of lines in 1d-neighborhood. local res = { from = offset_to_pos(span.from) } -- Convert empty span to empty region if span.from < span.to then res.to = offset_to_pos(span.to - 1) end return res end local is_region_inside = function(region) local res = line_start <= region.from.line if region.to ~= nil then res = res and (region.to.line <= line_end) end return res end return { n_neighbors = n_neighbors, region = reference_region, ['1d'] = neigh1d, ['2d'] = neigh2d, pos_to_offset = pos_to_offset, offset_to_pos = offset_to_pos, region_to_span = region_to_span, span_to_region = span_to_region, is_region_inside = is_region_inside, } end -- Utilities ------------------------------------------------------------------ H.error = function(msg) error('(mini.surround) ' .. 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.surround) ', 'WarningMsg' }) -- Avoid hit-enter-prompt local max_width = vim.o.columns * math.max(vim.o.cmdheight - 1, 0) + vim.v.echospace local chunks, 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 -- 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.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) local no_global_s_mapping = not H.has_global_mapping(mode, 's') if no_global_s_mapping and lhs:find('^s.') ~= nil then vim.keymap.set(mode, 's', '') end end H.has_global_mapping = function(mode, lhs) for _, map in ipairs(vim.api.nvim_get_keymap(mode)) do if map.lhs == lhs then return true end end return false end H.get_line_cols = function(line_num) return vim.fn.getline(line_num):len() end H.string_find = function(s, pattern, init) init = init or 1 -- Match only start of full string if pattern says so. -- This is needed because `string.find()` doesn't do this. -- Example: `string.find('(aaa)', '^.*$', 4)` returns `4, 5` if pattern:sub(1, 1) == '^' then if init > 1 then return nil end return string.find(s, pattern) end -- Handle patterns `x.-y` differently: make match as small as possible. This -- doesn't allow `x` be present inside `.-` match, just as with `yyy`. Which -- also leads to a behavior similar to punctuation id (like with `va_`): no -- covering is possible, only next, previous, or nearest. local check_left, _, prev = string.find(pattern, '(.)%.%-') local is_pattern_special = check_left ~= nil and prev ~= '%' if not is_pattern_special then return string.find(s, pattern, init) end -- Make match as small as possible local from, to = string.find(s, pattern, init) if from == nil then return end local cur_from, cur_to = from, to while cur_to == to do from, to = cur_from, cur_to cur_from, cur_to = string.find(s, pattern, cur_from + 1) end return from, to end ---@param arr table List of items. If item is list, consider as set for --- product. Else - make it single item list. ---@private H.cartesian_product = function(arr) if not (type(arr) == 'table' and #arr > 0) then return {} end arr = vim.tbl_map(function(x) return vim.islist(x) and x or { x } end, arr) local res, cur_item = {}, {} local process process = function(level) for i = 1, #arr[level] do table.insert(cur_item, arr[level][i]) if level == #arr then -- Flatten array to allow tables as elements of step tables table.insert(res, H.tbl_flatten(cur_item)) else process(level + 1) end table.remove(cur_item, #cur_item) end end process(1) return res end H.wrap_callable_table = function(x) if vim.is_callable(x) and type(x) == 'table' then return function(...) return x(...) end end return x end H.tbl_flatten = function(x) return vim.iter(x):flatten(math.huge):totable() end -- TODO: Remove after compatibility with Neovim=0.10 is dropped H.highlight_range = function(...) vim.hl.range(...) end if vim.fn.has('nvim-0.11') == 0 then H.highlight_range = function(...) vim.highlight.range(...) end end return MiniSurround