Breaking Changes: Following `main`

[kylechui]

I will be using this thread as the main place to notify users of breaking changes, so subscribe to this issue to stay up to date about changes that may affect your configuration. Furthermore, breaking commits will be flagged with a !, e.g. refactor!: ..., so if you notice one of those commit messages when updating, refer to this issue.

Thanks to everybody for using this plugin, and sorry for the inconvenience!

[kylechui]

As of #66, the default behavior for handling invalid keys into the delimiter table is no longer to surround using the key on the left and right hand side, but rather to throw an error message. For more information, see :h nvim-surround.delimiters.invalid_key_behavior. To re-enable the old default behavior, use the following in your configuration:

require("nvim-surround").setup({
    delimiters = {
        invalid_key_behavior = function(char)
            return { char, char }
        end,
    }
})

[kylechui]

Forgot to mention this (sorry!), but also as of #66, the provided function utils.get_input() has been deprecated in favor of using the built-in vim.fn.input(). The documentation will be patched shortly, see the default config for more details (in particular, the leading comment about keyboard interrupts).

[kylechui]

As of #92, the default keymaps for normal-mode surrounds have had their names changed:

• insert → normal
• insert_line → normal_cur

The new naming scheme reflects that insert means insert-mode mapping, while normal means normal-mode mapping. Furthermore, the _cur suffix means that the mapping operates on the current line, while the _line suffix means that the mapping will place the delimiter pair on new lines. See :h nvim-surround.keymaps for more details.

[kylechui]

With the introduction of #113, quite a few breaking changes have been introduced.

Configuration

• The delimiters table has been renamed to surrounds
• pairs and separators have been deprecated; store surround keys directly in surrounds
  • The surround values have also been changed, see :h nvim-surround.configuration for details
• highlight_motion has been renamed to highlight
• An argument table is no longer passed into the function used to create the surround by default (see Pass 'text to be surrounded' into custom callback function used to determine left and right surroundings #29, I doubt anybody made use of this)

Please see the default configuration and :h nvim-surround.configuration for details/examples.

Behavior

• The default invalid_key_behavior now takes the input character and adds/modifies it on the left/right. For example, by default | is not configured as a surround key:

    Old text                    Command         New text
    some_text                   ysiw|           |some_text|
    |some_text|                 ds|             some_text
    |some_text|                 cs|b            (some_text)

• The behavior for modifying deleting/changing open pairs is slightly different, see this commit.

[kylechui]

With the introduction of #136, some configuration options have been renamed to better reflect their actual purpose:

• highlight_motion → highlight
• NvimSurroundHighlightTextObject → NvimSurroundHighlight
• The textobject key for require("nvim-surround.config").get_selection() has been replaced by the motion key. This allows for better compatibility with targets.vim and similar plugins that define their own text-objects. All existing textobject keys just need to be pre-pended with a to represent the correct motion, e.g.

-- Old configuration
require("nvim-surround.config").get_selection({
    textobject = ")",
})
-- New configuration
require("nvim-surround.config").get_selection({
    motion = "a)",
})

[kylechui]

As of 87839e1, "smart" quotes have now been removed from nvim-surround. Now, modifying quotes will exclusively modify the immediate surrounding pair, instead of trying to compute some "quote balancing" to figure out which pair to delete. For example, running ds" on the following text with the cursor at *:

-- Original text
local str = "This string has "invalid quo*tes" in it!"
-- Old behavior (jumps to the second pair and deletes)
local str = "This string has "invalid quotes in it!
-- New behavior (doesn't jump, deleting the immediate surrounding pair)
local str = "This string has invalid quotes in it!"

Please see #153 for the rationale behind this decision.

[kylechui]

Note: If your configuration does not define invalid_key_behavior, this has no effect on you.

As of ebdd22d, custom invalid_key_behavior functions will now parse control and multi-byte characters, e.g. if your setup contains:

require("nvim-surround").setup({
    surrounds = {
        invalid_key_behavior = {
            add = function(char) -- This function now accepts control chars
                return { { char }, { char } }
            end
        }
        -- Note that there is no surround for <CR>
    }
}

Then ysiw<CR> will surround words with a carriage return literal, e.g.

word
-- ysiw<CR>
^Mword^M

[kylechui]

As of #360, number prefixes for surrounds work slightly differently for adding new surrounds to the buffer. In particular, the count preceding the <Plug>(nvim-surround-normal) keymap will no longer multiply against any counts in the following motion; rather, it will refer to the number of delimiter pairs to add around the motion. More concretely:

-- Current buffer contents, with cursor on *
this *is a sentence with quite a few words
-- Old behavior, after `3ys2w)`
-- The 3 prefix multiplies against the 2 in the motion to surround the following 6 words once
this (is a sentence with quite a) few words
-- New behavior after `3ys2w)`
-- The 3 prefix indicates that the next 2 words will be surrounded 3 times
this (((is a))) sentence with quite a few words

[kylechui]

As of #296 the keymaps field is no longer available as a part of the setup command. Please see :h nvim-surround.migrating.v3_to_v4 for details on how to configure keymaps in v4.