Usage
The plugin defines two commands, :SidewaysLeft and :SidewaysRight, which
move the item under the cursor left or right, where an "item" is defined by a
delimiter. As an example:
pass
Placing the cursor on "two" and executing :SidewaysLeft, the "one" and "two"
arguments will switch their places, resulting in this:
pass
In this case, the delimiter is a comma. The plugin currently works with various other cases and it's intended to make the process configurable. While this particular example is in python, this should work for arguments in many different languages that use round braces to denote function calls.
For ruby and eruby, it detects method calls without braces as well:
# changes to:
link_to 'Something', user_registration_path
Apart from functions, it works for square-bracket lists in dynamic languages:
If you experiment with this example, you'll find that you can move the entire second list around, as long as the cursor is on one of the inner brackets. The plugin takes into consideration nested structures.
It also works for multiline lists. Try experimenting with this example:
style="color: red;"
something="other">
Example
div>
It's highly recommended to map the two main commands to convenient keys. For
example, mapping them to
nnoremap
The plugin also provides the commands :SidewaysJumpLeft and
:SidewaysJumpRight, which move the cursor left and right by items.
Other things that sideways works for:
CSS declarations:
Lists within CSS declarations:
HTML attributes:
Handlebars components:
Cucumber tables:
| input_1 | input_2 | button | output |
| 20 | 30 | add | 50 |
| 2 | 5 | add | 7 |
| 0 | 40 | add | 40 |
Rust template arguments:
Rust return type (a special case since there's always just one, useful as a text object):
Go lists:
C++ templates:
* Relies on "<" being surrounded by non-whitespace, or considers it a
* comparison. Parsing C++ is tricky.
*/
std::unordered_map
Javascript-like objects:
OCaml lists:
LaTeX align/tabular:
a & b \\
c & d
\end{tabular}
LaTeX equations:
\[e^x = \sum_{n = 0}^{\infty} \frac{x^n}{n!}\]
Typescript enum values:
code: 200 | 404 | 500;
}
Python imports, for loops, return clauses:
for value, index in enumerate(items):
pass
return one, two, three
Vim comma-separated settings:
set completeopt=menuone,noinsert
set diffopt+=algorithm:patience,indent-heuristic,iwhite,linematch:60,vertical
Elixir functions:
The plugin is customizable -- take a look at :help sideways-customization
for instructions on how to implement support for other kinds of lists.
Bonus functionality
Text objects
The plugin's machinery makes it easy to implement an "argument" text object. There are two mappings provided:
SidewaysArgumentTextobjA
SidewaysArgumentTextobjI
These are the outer and inner text objects, respectively. To use them, you need to create mappings in your configuration files. Something like this:
xmap aa
omap ia
xmap ia
This will map the "a" text object to operate on an "argument". So, you can
perform daa to delete an argument, cia to change an argument, and so on.
See :help text-objects for more information.
Also, a useful plugin to use alongside sideways is fieldtrip. This defines a submode for sideways.vim.
Adding items
The plugin defines mappings to add new items to the list as well. There's four of them that mirror the i, a, I, and A built-in keybindings:
SidewaysArgumentInsertBefore
SidewaysArgumentAppendAfter
SidewaysArgumentInsertFirst
SidewaysArgumentAppendLast
However, they're not mapped by default and you need to pick ones that are convenient for you. As an example:
nmap
nmap
nmap
The mnemonic in this case would be leader-"sideways"-action. Given the following simple example in ruby:
With the cursor on "two", you can insert a new argument before the current item by using
Add an item after the current one by using
Prepend an item to the start of the list with
Push an item at the end with
This should work for all lists that are supported for the plugin, including HTML attributes, semicolon-separated CSS declarations, etc. If each existing list item is on a separate line (and there's at least two), the plugin assumes the new item should be on a new line as well:
one,
two,
three
)
# Append an item at the end:
function_call(
one,
two,
three,
NEW
)
Again, these mappings are not created by default -- copy the suggested ones to your vimrc, or create your own.
If you set g:sideways_add_item_cursor_restore to 1 and your vim has the +textprop feature, the plugin will jump back to where you triggered the mapping when you leave insert mode.
Note, however, that this relies on the InsertLeave autocommand, so if you exit insert mode via Ctrl+C (which doesn't trigger it), it won't jump until the next time you leave insert mode normally. If exiting via Ctrl+C is a part of your workflow, it's recommended you keep this setting off.