Home

Awesome

<!-- LTeX: enabled=false -->

nvim-various-textobjs 🟪🔷🟡

<!-- LTeX: enabled=true --> <a href="https://dotfyle.com/plugins/chrisgrieser/nvim-various-textobjs"> <img alt="badge" src="https://dotfyle.com/plugins/chrisgrieser/nvim-various-textobjs/shield"/></a>

Bundle of more than 30 new textobjects for Neovim.

Table of Contents

<!-- toc --> <!-- tocstop -->

List of Text Objects

<!-- vale off --> <!-- LTeX: enabled=false -->
textobjectdescriptioninner / outerforward-seekingdefault keymapsfiletypes (for default keymaps)
indentationsurrounding lines with same or higher indentationsee overview from vim-indent-object-ii, ai, aI, (iI)all
restOfIndentationlines down with same or higher indentation--Rall
greedyOuterIndentationouter indentation, expanded to blank lines; useful to get functions with annotationsouter includes a blank, like ap/ip-ag/igall
subwordlike iw, but treating - and _ as word delimiters and only part of camelCaseouter includes trailing _,-, or space-iS/aSall
toNextClosingBracketfrom cursor to next closing ], ), or }-smallCall
toNextQuotationMarkfrom cursor to next unescaped1 ", ', or `-smallQall
anyQuotebetween any unescaped1 ", ', or ` in a lineouter includes the quotation markssmalliq/aqall
anyBracketbetween any (), [], or {} in a lineouter includes the bracketssmallio/aoall
restOfParagraphlike }, but linewise--rall
entireBufferentire buffer as one text object--gGall
nearEoLfrom cursor position to end of line, minus one character--nall
lineCharacterwisecurrent line, but characterwiseouter includes indentation and trailing spaces-i_/a_all
columncolumn down until indent or shorter line. Accepts {count} for multiple columns.--|all
valuevalue of key-value pair, or right side of a assignment, excl. trailing comment (in a line)outer includes trailing commas or semicolonssmalliv/avall
keykey of key-value pair, or left side of a assignmentouter includes the = or :smallik/akall
urlworks with http[s] or any other protocol-bigLall
numbernumbers, similar to <C-a>inner: only pure digits, outer: number including minus sign and decimal pointsmallin/anall
diagnosticLSP diagnostic (requires built-in LSP)-∞!all
closedFoldclosed foldouter includes one line after the last folded linebigiz/azall
chainMemberfield with optional call, like .foo(param) or .barouter includes the leading . (or :)smallim/amall
visibleInWindowall lines visible in the current window--gwall
restOfWindowfrom the cursorline to the last line in the window--gWall
lastChangeLast non-deletion-change, yank, or paste.2--g;all
mdlinkmarkdown link like [title](url)inner is only the link title (between the [])smallil/almarkdown, toml
mdEmphasismarkdown text enclosed by *, **, _, __, ~~, or ==inner is only the emphasis contentsmallie/aemarkdown
mdFencedCodeBlockmarkdown fenced code (enclosed by three backticks)outer includes the enclosing backticksbigiC/aCmarkdown
cssSelectorclass in CSS like .my-classouter includes trailing comma and spacesmallic/accss, scss
cssColorcolor in CSS (hex, rgb, or hsl)inner includes only the color valuesmalli#/a#css, scss
htmlAttributeattribute in html/xml like href="foobar.com"inner is only the value inside the quotessmallix/axhtml, xml, css, scss, vue
doubleSquareBracketstext enclosed by [[]]outer includes the four square bracketssmalliD/aDlua, shell, neorg, markdown
shellPipesegment until/after a pipe character (|)outer includes the pipesmalliP/aPbash, zsh, fish, sh
pyTripleQuotespython strings surrounded by three quotes (regular or f-string)inner excludes the """ or '''-iy/aypython
notebookCellcell delimited by double percent comment, such as # %%outer includes the bottom cell border-iN/aNall
<!-- vale on --> <!-- LTeX: enabled=true -->

Installation

Variant 1: Have nvim-various-textobjs set up all the keybindings from the table above for you.

-- lazy.nvim
{
	"chrisgrieser/nvim-various-textobjs",
	event = "UIEnter",
	opts = { useDefaultKeymaps = true },
},

-- packer
use {
	"chrisgrieser/nvim-various-textobjs",
	config = function () 
		require("various-textobjs").setup({ useDefaultKeymaps = true })
	end,
}

Variant 2: Use your own keybindings. See the Configuration section for information on setting your own keymaps.

-- lazy.nvim
{
	"chrisgrieser/nvim-various-textobjs",
	lazy = true,
	keys = {
		-- ...
	},
},

-- packer
use { "chrisgrieser/nvim-various-textobjs" }

[!TIP] You can also use the disabledKeymaps config option to disable only some default keymaps.

Configuration

Options

The .setup() call is optional if you are fine with the defaults below.

-- default config
require("various-textobjs").setup {
	-- set to 0 to only look in the current line
	lookForwardSmall = 5,
	lookForwardBig = 15,

	-- use suggested keymaps (see overview table in README)
	useDefaultKeymaps = false,

	-- disable only some default keymaps, e.g. { "ai", "ii" }
	disabledKeymaps = {},

	-- display notification if a text object is not found
	notifyNotFound = true,
}

Use your own keybindings

If you want to set your own keybindings, you can do so by calling the respective functions. The function names correspond to the textobject names from the overview table.

[!NOTE] For dot-repeat to work, you have to call the motions as Ex-commands. When using function() require("various-textobjs").diagnostic() end as third argument of the keymap, dot-repeatability is not going to work.

-- example: `U` for url textobj
vim.keymap.set({ "o", "x" }, "U", '<cmd>lua require("various-textobjs").url()<CR>')

-- example: `as` for outer subword, `is` for inner subword
vim.keymap.set({ "o", "x" }, "as", '<cmd>lua require("various-textobjs").subword("outer")<CR>')
vim.keymap.set({ "o", "x" }, "is", '<cmd>lua require("various-textobjs").subword("inner")<CR>')

For most text objects, there is only one parameter which accepts "inner" or "outer". There are two exceptions for that:

-- 1. THE INDENTATION TEXTOBJ requires two parameters, the first for
-- exclusion of the starting border, the second for the exclusion of ending border
vim.keymap.set(
	{ "o", "x" },
	"ii",
	'<cmd>lua require("various-textobjs").indentation("inner", "inner")<CR>'
)
vim.keymap.set(
	{ "o", "x" },
	"ai",
	'<cmd>lua require("various-textobjs").indentation("outer", "inner")<CR>'
)

-- an additional parameter can be passed to control whether blank lines are included
vim.keymap.set(
	{ "o", "x" },
	"ai",
	'<cmd>lua require("various-textobjs").indentation("outer", "inner", "noBlanks")<CR>'
)

-- 2. THE DIAGNOSTIC TEXTOBJ accepts `"wrap"` or `"nowrap"`
vim.keymap.set({ "o", "x" }, "!", '<cmd>lua require("various-textobjs").diagnostic("wrap")<CR>')

Advanced Usage / API

All textobjects can also be used as an API to modify their behavior or create custom commands. Here are some examples:

ii on unindented line should select entire buffer

Using a simple if-else-block, you can create a hybrid of the inner indentation text object and the entire-buffer text object, if you prefer that kind of behavior:

-- when on unindented line, `ii` should select entire buffer
vim.keymap.set("o", "ii", function()
	if vim.fn.indent(".") == 0 then
		require("various-textobjs").entireBuffer()
	else
		require("various-textobjs").indentation("inner", "inner")
	end
end)

Smarter gx

The code below retrieves the next URL (within the amount of lines configured in the setup call), and opens it in your browser. As opposed to vim's built-in gx, this is forward-seeking, meaning your cursor does not have to stand on the URL.

vim.keymap.set("n", "gx", function()
	-- select URL
	require("various-textobjs").url()

	-- plugin only switches to visual mode when textobj is found
	local foundURL = vim.fn.mode():find("v")
	if not foundURL then return end

	-- retrieve URL with the z-register as intermediary
	vim.cmd.normal { '"zy', bang = true }
	local url = vim.fn.getreg("z")
	vim.ui.open(url) -- requires nvim 0.10
end, { desc = "URL Opener" })

You could go even further: When no URL can be found by various-textobjs, you could retrieve all URLs in the buffer and select one to open. (The URL-pattern used by this plugin is exposed for this purpose.)

vim.keymap.set("n", "gx", function()
	require("various-textobjs").url()
	local foundURL = vim.fn.mode():find("v")
	if foundURL then
		vim.cmd.normal('"zy')
		local url = vim.fn.getreg("z")
		vim.ui.open(url)
	else
		-- find all URLs in buffer
		local urlPattern = require("various-textobjs.charwise-textobjs").urlPattern
		local bufText = table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), "\n")
		local urls = {}
		for url in bufText:gmatch(urlPattern) do
			table.insert(urls, url)
		end
		if #urls == 0 then return end

		-- select one, use a plugin like dressing.nvim for nicer UI for
		-- `vim.ui.select`
		vim.ui.select(urls, { prompt = "Select URL:" }, function(choice)
			if choice then vim.ui.open(choice) end
		end)
	end
end, { desc = "URL Opener" })

Delete Surrounding Indentation

Using the indentation textobject, you can also create custom indentation-related utilities. A common operation is to remove the line before and after an indentation. Take for example this case where you are removing the foo condition:

-- before
if foo then
	print("bar") -- <- cursor is on this line
	print("baz")
end

-- after
print("bar")
print("baz")

The code below achieves this by dedenting the inner indentation textobject (essentially running <ii), and deleting the two lines surrounding it. As for the mapping, dsi should make sense since this command is similar to the ds operator from vim-surround but performed on an indentation textobject. (It is also an intuitive mnemonic: delete surrounding indentation.)

vim.keymap.set("n", "dsi", function()
	-- select outer indentation
	require("various-textobjs").indentation("outer", "outer")

	-- plugin only switches to visual mode when a textobj has been found
	local indentationFound = vim.fn.mode():find("V")
	if not indentationFound then return end

	-- dedent indentation
	vim.cmd.normal { "<", bang = true }

	-- delete surrounding lines
	local endBorderLn = vim.api.nvim_buf_get_mark(0, ">")[1]
	local startBorderLn = vim.api.nvim_buf_get_mark(0, "<")[1]
	vim.cmd(tostring(endBorderLn) .. " delete") -- delete end first so line index is not shifted
	vim.cmd(tostring(startBorderLn) .. " delete")
end, { desc = "Delete Surrounding Indentation" })

Yank Surrounding Indentation

Similarly, you can also create a ysii command to yank the two lines surrounding an indentation textobject. (Not using ysi, since that blocks surround commands like ysi)). Using nvim_win_[gs]et_cursor(), you make the operation sticky, meaning the cursor is not moved. vim.highlight.range is used to highlight the yanked text, to imitate the effect of vim.highlight.yank.

vim.keymap.set("n", "ysii", function()
	local startPos = vim.api.nvim_win_get_cursor(0)

	-- identify start- and end-border
	require("various-textobjs").indentation("outer", "outer")
	local indentationFound = vim.fn.mode():find("V")
	if not indentationFound then return end
	vim.cmd.normal { "V", bang = true } -- leave visual mode so the '< '> marks are set

	-- copy them into the + register
	local startLn = vim.api.nvim_buf_get_mark(0, "<")[1] - 1
	local endLn = vim.api.nvim_buf_get_mark(0, ">")[1] - 1
	local startLine = vim.api.nvim_buf_get_lines(0, startLn, startLn + 1, false)[1]
	local endLine = vim.api.nvim_buf_get_lines(0, endLn, endLn + 1, false)[1]
	vim.fn.setreg("+", startLine .. "\n" .. endLine .. "\n")

	-- highlight yanked text
	local ns = vim.api.nvim_create_namespace("ysi")
	vim.api.nvim_buf_add_highlight(0, ns, "IncSearch", startLn, 0, -1)
	vim.api.nvim_buf_add_highlight(0, ns, "IncSearch", endLn, 0, -1)
	vim.defer_fn(function() vim.api.nvim_buf_clear_namespace(0, ns, 0, -1) end, 1000)

	-- restore cursor position
	vim.api.nvim_win_set_cursor(0, startPos)
end, { desc = "Yank surrounding indentation" })

Indent Last Paste

The lastChange textobject can be used to indent the last text that was pasted. This is useful in languages such as Python where indentation is meaningful and thus formatters are not able to automatically indent everything for you.

If you do not use P for upwards paste, "shift paste" serves as a great mnemonic.

vim.keymap.set("n", "P", function()
	require("various-textobjs").lastChange()
	local changeFound = vim.fn.mode():find("v")
	if changeFound then vim.cmd.normal { ">", bang = true } end
end

Other Ideas?

If you have some other useful ideas, feel free to share them in this repo's discussion page.

Limitations & Non-Goals

Other Text Object Plugins

<!-- vale Google.FirstPerson = NO -->

Credits

Thanks

In my day job, I am a sociologist studying the social mechanisms underlying the digital economy. For my PhD project, I investigate the governance of the app economy and how software ecosystems manage the tension between innovation and compatibility. If you are interested in this subject, feel free to get in touch.

I also occasionally blog about vim: Nano Tips for Vim

<a href='https://ko-fi.com/Y8Y86SQ91' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>

Footnotes

  1. This respects vim's quoteescape option. ↩ ↩2

  2. The lastChange textobject does not work well with plugins that manipulate paste operations such as yanky.nvim or plugins that auto-save the buffer. ↩