🪓 substitute.nvim

substitute.nvim aim is to provide new operator motions to make it very easy to perform quick substitutions and exchange.

If you are familiar with svermeulen/vim-subversive and tommcdo/vim-exchange, this plugin does almost the same but rewritten in lua (and I hope this will be more maintainable, readable and efficient).

✨ Features

• 🪓 Substitute operator
• 🔁 Substitute over range motion
• 🔀 Exchange operator

See this plugin in action

⚡️ Requirements

• Neovim >= 0.8.0

(Neovim 0.6.0 compat)

📦 Installation

Install the plugin with your preferred package manager:

Lazy.nvim

{
    "gbprod/substitute.nvim",
    opts = {
        -- your configuration comes here
        -- or leave it empty to use the default settings
        -- refer to the configuration section below
    }
}

⚙️ Configuration

For the basic setup with default configurations:

require('substitute').setup()

Substitute comes with the following defaults:

require('substitute').setup({
  on_substitute = nil,
  yank_substituted_text = false,
  preserve_cursor_position = false,
  modifiers = nil,
  highlight_substituted_text = {
    enabled = true,
    timer = 500,
  },
  range = {
    prefix = "s",
    prompt_current_text = false,
    confirm = false,
    complete_word = false,
    subject = nil,
    range = nil,
    suffix = "",
    auto_apply = false,
    cursor_position = "end",
  },
  exchange = {
    motion = false,
    use_esc_to_cancel = true,
    preserve_cursor_position = false,
  },
})

More details on these options is available in the sections below corresponding to the different features.

🪓 Substitute operator

This plugin contains no default mappings and will have no effect until you add your own maps to it.

-- Lua
vim.keymap.set("n", "s", require('substitute').operator, { noremap = true })
vim.keymap.set("n", "ss", require('substitute').line, { noremap = true })
vim.keymap.set("n", "S", require('substitute').eol, { noremap = true })
vim.keymap.set("x", "s", require('substitute').visual, { noremap = true })

Then you can then execute s<motion> to substitute the text object provided by the motion with the contents of the default register (or an explicit register if provided). For example, you could execute siw to replace the current word under the cursor with the current yank, or sip to replace the paragraph, etc. (this action is dot-repeatable)

Note: in this case you will be shadowing the change character key s so you will have to use the longer form cl.

Each functions (operator, line, eol and visual) are configurable:

lua require('substitute').operator({
  count = 1,       -- number of substitutions
  register = "a",  -- register used for substitution
  motion = "iw",   -- only available for `operator`, this will automatically use
                   -- this motion for substitution instead of waiting for.
  modifiers = nil, -- this allows to modify substitued text, will override the default
                   -- configuration (see below)
})

⚙️ Configuration

on_substitute

Default : nil

Function that will be called each times a substitution is made. This function takes a param argument that contains the register used for substitution.

yank_substituted_text

Default : false

If true, when performing a substitution, substitued text is pushed into the default register.

highlight_substituted_text.enabled

Default : true

If true will temporary highlight substitued text.

highlight_substituted_text.timer

Default : 500

Define the duration of highlight.

preserve_cursor_position

Default : false

If true, the cursor position will be preserved when performing a substitution.

modifiers

Default : nil

Could be a function or a table of transformations that will be called to modify substitued text. See modifiers section below.

➰ Modifiers

Modifiers are used to modify the text before substitution is performed. You can chain those modifiers or even use a function to dynamicly choose modifier depending on the context.

Available modifiers are:

• linewise : will create a new line for substitution ;
• reindent : will reindent substitued text ;
• trim : will trim substitued text ;
• join : will join lines of substitued text.

Examples

If you want to create a new line for substitution and reindent, you can use:

require('substitute').operator({
  modifiers = { 'linewise', 'reindent' },
})

If you want to trim and join lines of substitued text, you can use:

require('substitute').operator({
  modifiers = { 'join', 'trim' },
})

If you want to trim text but only if you substitute text in a charwise motion, you can use:

require('substitute').operator({
  modifiers = function(state)
    if state.vmode == 'char' then
      return { 'trim' }
    end
  end,
})

If you always want to reindent text when making a linewise substitution, you can use:

require('substitute').operator({
  modifiers = function(state)
    if state.vmode == 'line' then
      return { 'reindent' }
    end
  end,
})

🤝 Integration

<details> <summary><b>gbprod/yanky.nvim</b></summary>

To enable gbprod/yanky.nvim swap when performing a substitution, you can add this to your setup:

require("substitute").setup({
  on_substitute = require("yanky.integration").substitute(),
})

</details> <details> <summary><b>svermeulen/vim-yoink</b></summary>

To enable vim-yoink swap when performing a substitution, you can add this to your setup:

require("substitute").setup({
  on_substitute = function(_)
    vim.cmd("call yoink#startUndoRepeatSwap()")
  end,
})

vim-yoink does not support swapping when doing paste in visual mode. With this plugin, you can add thoss mappings to enable it :

vim.keymap.set("x", "p", require('substitute').visual, { noremap = true })
vim.keymap.set("x", "P", require('substitute').visual, { noremap = true })

</details>

🔁 Substitute over range motion

Another operator provided allows specifying both the text to replace and the line range over which to apply the change by using multiple consecutive motions.

vim.keymap.set("n", "<leader>s", require('substitute.range').operator, { noremap = true })
vim.keymap.set("x", "<leader>s", require('substitute.range').visual, { noremap = true })
vim.keymap.set("n", "<leader>ss", require('substitute.range').word, { noremap = true })

After adding this map, if you execute <leader>s<motion1><motion2> then the command line will be filled with a substitute command that allow to replace the text given by motion1 by the text will enter in the command line for each line provided by motion2.

Alternatively, we can also select motion1 in visual mode and then hit <leader>s<motion2> for the same effect.

For convenience, <leader>ss<motion2> can be used to select complete word under the cursor as motion1 (complete word means that complete_word options is override to true so is different from <leader>siwip which will not require that there be word boundaries on each match).

You can select the default replacement value by selecting a register. Eg: "a<leader>s<motion1><motion2> will use the content of a register as replacement value.

You can override any default configuration (described later) by passing this to the operator function. By example, this will use S as prefix of the substitution command (and use tpope/vim-abolish):

vim.keymap.set("n", "<leader>S", function ()
    require('substitute.range').operator({ prefix = 'S' })
end, { noremap = true })

⚙️ Configuration

range.prefix

Default : s

Substitution command that will be used (set it to S to use tpope/vim-abolish substitution by default).

range.suffix

Default : ""

Suffix added at the end of the substitute command. For example, it can be used to not save substitution history calls by adding | call histdel(':', -1).

range.prompt_current_text

Default : false

Substitution command replace part will be set to the current text. Eg. instead of s/pattern//g you will have s/pattern/pattern/g.

range.confirm

Default : false

Will ask for confirmation for each substitutions.

range.complete_word

Default : false

Will require that there be word boundaries on each match (eg: \<word\> instead of word).

range.group_substituted_text

Default : false

This will capture substituted text as you can use \1 to quickly reuse it.

range.subject

Default : nil

This allows you to control how the subject (to be replaced) is resolved. It accepts either a function, string, or a table with some special keys.

If it is a string that will be used directly. If it is a function it will be called when the operator is used, and should return the subject to be replaced. If it is a table you may provide one of the following keys with appropriate values:

• register = "a" Use the contents of this register as the subject.
• expand = "<cword>" Use the string given as the argument to vim.fn.expand() to get the subject.
• last_search = true Shortcut for `registe