wurli/split.nvim
github
17
1
1
1
split.nvim is a plugin which adds linebreaks to your code based on one or more
Lua patterns. Patterns may be simple like "," to split text by commas, or
more complex like "[%.?!]%s+" to split text so each sentence ends up on
its own line.
Features:
Automatic indentation applied to the split region. This is the same indentation used by your normal
==, so spacing should end up the way you like it.Awareness of common text objects like
(),{},"", etc. This means your code is much less likely to get completely borked by the operation.Comment awareness. If the region you're splitting over contains both commented and uncommented code, splits won't get added within the comments (this is configurable). This also significantly decreases the bork-factor during splitting.
split.nvim makes it very easy to insert the linebreaks either before, after, or on the split pattern. Nice if you write SQL the right way.
Operator-pending mode and dot-repeat.
An interactive mode so you don't need to set a million keymaps to get fine-grained control.
These features all combine to give a simple, powerful tool which integrates
very nicely with Neovim's existing set of text manipulation keymappings
(especially J and gJ). Not convinced? Give it a try! It's a classic green
eggs and ham plugin.
Installation
split.nvim is easy to install using your favourite plugin manager. Here's how you can install it using Lazy:
{
"wurli/split.nvim",
opts = {
keymaps = {
-- Other keymaps are available :) these ones will be used
-- by default.
["gs"] = {
pattern = ",",
operator_pending = true,
interactive = false,
},
["gss"] = {
pattern = ",",
operator_pending = false,
interactive = false,
},
["gS"] = {
pattern = ",",
operator_pending = true,
interactive = true,
},
["gSS"] = {
pattern = ",",
operator_pending = false,
interactive = true,
},
},
},
},
Configuration
split.nvim supports a plethora of configuration options, although the defaults should (hopefully) be suitable for the majority of users. For a complete list of options, please see the documentation. Here's a quick example to whet your appetite:
{
keymaps = {
-- Here, gs and gss give a mapping to split lines by commas and
-- semicolons. This doesn't enter interactive mode.
["gs"] = {
pattern = "[,;]",
operator_pending = true,
},
["gss"] = {
pattern = "[,;]",
operator_pending = false,
},
-- Here, gS and gSS give a mapping to enter interactive split mode...
["gS"] = {
interactive = true,
operator_pending = true,
},
["gSS"] = {
interactive = true,
operator_pending = false,
},
},
interactive_options = {
-- In interactive mode, the user can press ',' to split by commas
-- and semicolons, or '|' to split by the pipe operator. The
-- pipe operator pattern also checks if the current line is an
-- uncommented OCaml line, and if so, puts the pipe at the
-- start of the line.
[","] = "[,;]",
["|"] = {
pattern = { "|>", "%%>%%" },
break_placement = function(line_info, opts)
if line_info.filetype == "ocaml" and not line_info.comment then
return "before_pattern"
end
return "after_pattern"
end
}
},
keymap_defaults = {
-- We can also override the plugin defaults for mappings. For
-- example, this option specifies that if we're writing SQL,
-- we should put the split pattern at the start of each line
-- unless we're writing a comment, e.g. for those who style
-- their SQL like this (the right way):
--
-- -- Before splitting
-- select foo, bar, baz
-- from table
--
-- -- After splitting
-- select foo
-- , bar
-- , baz
-- from table
break_placement = function(line_info, opts)
if line_info.filetype == "sql" and not line_info.comment then
return "before_pattern"
end
return "after_pattern"
end
},
-- If you don't want to include the default keymaps you can set this
-- to `false`
set_default_mappings = true
}
A note about usage
split.nvim differs from many similar plugins in that it is designed to be
primarily used in operator-pending mode. E.g. if your mappings are gs/gss
and you want to split arguments within some code like do_stuff(a = 1, b = 2, c = 3), you can first hit gs to enter operator-pending mode, then the
text-object ib (think 'in braces') to apply the split within the pair of
parentheses (). This is particularly handy because this will work even if
your cursor is before the parentheses themselves! ✨
You can also use gss to split an entire line, but since split.nvim will
by default not insert linebreaks within parentheses or quotes which lie within
the selected text, this will not do the same thing as gsib.
To learn more about operator-pending mode, see :help operator-pending and
:help text-objects.
Interactive mode
When split.nvim is called in interactive mode, the user will be prompted to enter options to perform the split. In this mode, special keys are used to enter non-standard options:
<C-x>can be used to enter a non-standard split pattern<Enter>can be used to cycle through the options for where linebreaks are placed relative to the split pattern<C-s>can be used to toggle whether the original line breaks should be retained in addition to the new ones.
To perform the split and exit interactive mode you should use one of the
keys specified by config.interactive_options. These are the options
you get out of the box:
",": Split on commas.";": Split on semicolons." ": Split on one or more whitespace characters."+": Split on+,-,/, and%, provided these are surrounded by one or more whitespace characters."<": Split by<,<=,==,>, or>=.".": Split text so that each sentence occupies a single line.
Similar work
There are a few other plugins that offer similar functionality. A detailed comparison to each of these is on my to-do list 😀