mirror of
https://github.com/junegunn/vim-easy-align.git
synced 2025-11-12 03:43:48 -05:00
2486b9c6df
- Preserve indentation when a line starts with a delimiter
- Useful for aligning multi-line method chains
- Renamed `margin_{left,right}` to `{left,right}_margin
- Makes it easier to type in (`l`, `r`)
- `margin_{left,right}` is still supported
- Margins can be specified as the number of spaces, or as an arbitrary string
247 lines
7.7 KiB
Plaintext
247 lines
7.7 KiB
Plaintext
vim-easy-align *vim-easy-align* *easy-align*
|
|
=========================================================================
|
|
|
|
A simple, easy-to-use Vim alignment plugin without too much ambition.
|
|
|
|
Author: Junegunn Choi
|
|
Source: https://github.com/junegunn/vim-easy-align
|
|
|
|
|
|
EasyAlign *:EasyAlign*
|
|
-------------------------------------------------------------------------
|
|
|
|
vim-easy-align defines `:EasyAlign` command in the visual mode.
|
|
|
|
| Mode | Command |
|
|
| ------------------------- | ------------------------------------------- |
|
|
| Interactive mode | :EasyAlign |
|
|
| Using predefined rules | :EasyAlign [FIELD#] DELIMITER_KEY [OPTIONS] |
|
|
| Using regular expressions | :EasyAlign [FIELD#] /REGEXP/ [OPTIONS] |
|
|
|
|
The commands will go into the interactive mode when no argument is given.
|
|
For convenience, it is advised that you define a mapping for triggering it
|
|
in your `.vimrc`.
|
|
|
|
vnoremap <silent> <Enter> :EasyAlign<cr>
|
|
|
|
With this mapping, you can align selected lines with a few keystrokes.
|
|
|
|
1. <Enter> key to start interactive EasyAlign command
|
|
2. Optional Enter keys to switch justficiation mode (default: left)
|
|
3. Optional field number (default: 1)
|
|
1 Around the 1st occurrences of delimiters
|
|
2 Around the 2nd occurrences of delimiters
|
|
* Around all occurrences of delimiters
|
|
** Left-right alternating alignment around all delimiters
|
|
- Around the last occurrences of delimiters (`-1`)
|
|
-2 Around the second to last occurrences of delimiters
|
|
...
|
|
4. Delimiter key (a single keystroke)
|
|
<space> General alignment around whitespaces
|
|
= Operators containing equals sign (=, ==, !=, +=, &&=, ...)
|
|
: Suitable for formatting JSON or YAML
|
|
. Multi-line method chaining
|
|
, Multi-line method arguments. CSV.
|
|
| Table markdown
|
|
|
|
During the key sequence, <Enter> key will toggle right-justification mode.
|
|
|
|
Examples:
|
|
|
|
<Enter><space> Alignment around 1st whitespaces
|
|
<Enter>2<space> Alignment around 2nd whitespaces
|
|
<Enter>-<space> Alignment around the last whitespaces
|
|
<Enter>: Alignment around 1st colon
|
|
<Enter>= Alignment around 1st equals signs (and the likes)
|
|
<Enter>2= Alignment around 2nd equals signs (and the likes)
|
|
<Enter>3= Alignment around 3rd equals signs (and the likes)
|
|
<Enter>*= Alignment around all equals signs (and the likes)
|
|
<Enter>**= Left-right alternating alignment around all equals signs
|
|
<Enter><Enter>= Right-justified alignment around 1st equals signs
|
|
<Enter><Enter>**= Right-left alternating alignment around all equals signs
|
|
|
|
|
|
EasyAlign! *:EasyAlign!*
|
|
-------------------------------------------------------------------------
|
|
|
|
:EasyAlign! is the right-justification version of :EasyAlign command.
|
|
|
|
|
|
Non-interactive mode
|
|
--------------------
|
|
|
|
Instead of going into the interactive mode, you can type in arguments to
|
|
`:EasyAlign` command. In non-interactive mode, you can even use arbitrary
|
|
regular expressions.
|
|
|
|
" Using predefined alignment rules
|
|
:EasyAlign [FIELD#] DELIMITER_KEY [OPTIONS]
|
|
|
|
" Using arbitrary regular expressions
|
|
:EasyAlign [FIELD#] /REGEXP/ [OPTIONS]
|
|
|
|
For example, when aligning the following lines around colons and semi-colons,
|
|
|
|
apple;:banana::cake
|
|
data;;exchange:;format
|
|
|
|
try these commands:
|
|
|
|
- :EasyAlign /[:;]\+/
|
|
- :EasyAlign 2/[:;]\+/
|
|
- :EasyAlign */[:;]\+/
|
|
- :EasyAlign **/[:;]\+/
|
|
|
|
Notice that you can't append `\zs` to your regular expression to put delimiters
|
|
on the left. It can be done by providing additional options.
|
|
|
|
- :EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': '' }
|
|
|
|
Then we get:
|
|
|
|
apple;: banana:: cake
|
|
data;; exchange:; format
|
|
|
|
Options keys are fuzzy-matched, so you can write as follows:
|
|
|
|
- :EasyAlign * /[:;]\+/ { 'stl': 1, 'l': '' }
|
|
|
|
You can even omit spaces between the arguments, so concisely (or cryptically):
|
|
|
|
- :EasyAlign*/[:;]\+/{'s':1,'l':''}
|
|
|
|
Available options for each alignment are as follows.
|
|
|
|
| Atrribute | Type | Default |
|
|
| ---------------- | ---------------- | ----------------------- |
|
|
| left_margin | number or string | 0 |
|
|
| right_margin | number or string | 0 |
|
|
| stick_to_left | boolean | 0 |
|
|
| ignore_unmatched | boolean | 1 |
|
|
| ignores | array | `['String', 'Comment']` |
|
|
|
|
|
|
Partial alignment in blockwise-visual mode
|
|
-------------------------------------------------------------------------
|
|
|
|
In blockwise-visual mode (`CTRL-V`), EasyAlign command aligns only
|
|
the selected text in the block, instead of the whole lines in the range.
|
|
|
|
|
|
Ignoring delimiters in comments or strings *g:easy_align_ignores*
|
|
-------------------------------------------------------------------------
|
|
|
|
EasyAlign can be configured to ignore delimiters in certain syntax
|
|
highlight groups, such as code comments or strings. By default, delimiters
|
|
that are highlighted as code comments or strings are ignored.
|
|
|
|
" Default:
|
|
" If a delimiter is in a highlight group whose name matches
|
|
" any of the followings, it will be ignored.
|
|
let g:easy_align_ignores = ['Comment', 'String']
|
|
|
|
For example, the following paragraph
|
|
|
|
{
|
|
# Quantity of apples: 1
|
|
apple: 1,
|
|
# Quantity of bananas: 2
|
|
bananas: 2,
|
|
# Quantity of grape:fruits: 3
|
|
'grape:fruits': 3
|
|
}
|
|
|
|
becomes as follows on `<Enter>:`
|
|
|
|
{
|
|
# Quantity of apples: 1
|
|
apple: 1,
|
|
# Quantity of bananas: 2
|
|
bananas: 2,
|
|
# Quantity of grape:fruits: 3
|
|
'grape:fruits': 3
|
|
}
|
|
|
|
Naturally, this feature only works when syntax highlighting is enabled.
|
|
|
|
You can change the default rule by defining `g:easy_align_ignores` array.
|
|
|
|
" Ignore nothing!
|
|
let g:easy_align_ignores = []
|
|
|
|
Then you get,
|
|
|
|
{
|
|
# Quantity of apples: 1
|
|
apple: 1,
|
|
# Quantity of bananas: 2
|
|
bananas: 2,
|
|
# Quantity of grape: fruits: 3
|
|
'grape: fruits': 3
|
|
}
|
|
|
|
|
|
Handling unmatched lines *g:easy_align_ignore_unmatched*
|
|
-------------------------------------------------------------------------
|
|
|
|
Lines without any matching delimiter are ignored as well (except in
|
|
right-justification mode).
|
|
|
|
For example, when aligning the following code block around the colons,
|
|
|
|
{
|
|
apple: proc {
|
|
this_line_does_not_have_a_colon
|
|
},
|
|
bananas: 2,
|
|
grapefruits: 3
|
|
}
|
|
|
|
this is usually what we want.
|
|
|
|
{
|
|
apple: proc {
|
|
this_line_does_not_have_a_colon
|
|
},
|
|
bananas: 2,
|
|
grapefruits: 3
|
|
}
|
|
|
|
However, this default behavior is also configurable.
|
|
|
|
let g:easy_align_ignore_unmatched = 0
|
|
|
|
Then we get,
|
|
|
|
{
|
|
apple: proc {
|
|
this_line_does_not_have_a_colon
|
|
},
|
|
bananas: 2,
|
|
grapefruits: 3
|
|
}
|
|
|
|
|
|
Extending alignment rules *g:easy_align_delimiters*
|
|
-------------------------------------------------------------------------
|
|
|
|
let g:easy_align_delimiters = {
|
|
\ '>': { 'pattern': '>>\|=>\|>' },
|
|
\ '/': { 'pattern': '//\+' },
|
|
\ '#': { 'pattern': '#\+' },
|
|
\ ']': {
|
|
\ 'pattern': '[\[\]]',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0,
|
|
\ 'stick_to_left': 0
|
|
\ },
|
|
\ ')': {
|
|
\ 'pattern': '[()]',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0,
|
|
\ 'stick_to_left': 0
|
|
\ }
|
|
\ }
|
|
|
|
|