nvim-treesitter-textsubjects

Location and syntax aware text objects which *do what you mean*

Screen.Recording.2022-01-09.at.11.34.26.PM.mov

Quick Start

Note: This plugin requires nvim-treesitter to be installed and set up.

No configuration is required, just install the plugin.

It will setup the following text objects:

• ; will select a syntactical container (class, function, etc.) depending on your location in the syntax tree.
• i; will select the body of a syntactical container depending on your location in the syntax tree.
• . will select the most relevant part of the syntax tree depending on your location in it.

It will also setup a mapping for , to repeat the last selection.

Configuration

If you want to override the defaults, you can use the following configuration and modify it as needed.

require('nvim-treesitter-textsubjects').configure({
    prev_selection = ',',
    keymaps = {
        ['.'] = 'textsubjects-smart',
        [';'] = 'textsubjects-container-outer',
        ['i;'] = 'textsubjects-container-inner',
    },
})

Note: I know these names are a bit confusing, but naming them is quite difficult.

Text Subjects

Note: I'm open to adding more queries or support for another language, just open and issue or a PR and I can work with you to get the query working.

	container-inner	container-outer	smart
c	🟩	🟩	🟩
cpp	🟩	🟩	🟩
elixir	⬜	🟩	🟩
foam	⬜	🟩	🟩
go	🟩	🟩	🟩
javascript / jsx	⬜	🟩	🟩
julia	⬜	🟩	🟩
lua	🟩	🟩	🟩
php	🟩	🟩	🟩
python	🟩	🟩	🟩
r	🟩	🟩	🟩
ruby	🟩	🟩	🟩
rust	🟩	🟩	🟩
scss	⬜	⬜	🟩
typescript / tsx	⬜	🟩	🟩
fennel	🟩	🟩	🟩
nix	⬜	⬜	🟩

textsubjects-smart

Patterns: comments, consecutive line comments, function calls, function definitions, class definitions, loops, if statements, return values, arguments.

See queries/*/textsubjects-smart.scm for full information on the query.

textsubjects-container-outer

Patterns: Classes, structs, functions, methods.

See queries/*/textsubjects-container-outer.scm for full information on the query.

textsubjects-container-inner

Patterns: Inside Classes, structs, functions, methods.

See queries/*/textsubjects-container-inner.scm for full information on the query.

Custom Query

You can create your own text subjects by creating a Tree-sitter query that has ranges named range. This query file name can be provided in the keymaps about.

Ranges can be created as follows:

((comment) @_start @_end
     (#make-range! "range" @_start @_end))

See queries/*/textsubjects-smart.scm for examples or open an issue if you need any help writing a query.

Alternatives

• nvim-treesitter-textobjects: I still use this and it's a great plugin (especially the lookahead feature 😉). If you want to target the textobject exactly then this plugin is the way to go. However, it can quickly lead to having too many text object mappings (I had 8 before making this plugin) and it will always deal with whitespace based on the way you invoked it rather than handling this heuristically.
• nvim-treesitter-incremental-selection-mod: This is similar but doesn't act as a text objects. When incrementing the selection it will do so strictly by scope or by looking at the parent node which is often way too strict for practical use. For example, it will select all the arguments in (,) then can be expanded a few times to reach the next scope inside {,}, but these can both be selected more directly with ib and iB respectively so it would make more sense to skip them since the user probably doesn't want to select them. Incremental selection sounds nice but often isn't how people edit text (at least not me). On top of all this, it's strict with whitespace whereas this plugin will try to handle it heuristically.