mirror of
https://github.com/junegunn/vim-easy-align.git
synced 2025-11-11 19:33:50 -05:00
346 lines
10 KiB
Plaintext
346 lines
10 KiB
Plaintext
*easy_align.txt* A simple, easy-to-use Vim alignment plugin
|
|
|
|
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* *:EasyAlign!*
|
|
-------------------------------------------------------------------------
|
|
|
|
vim-easy-align defines `:EasyAlign` command in the visual mode.
|
|
(:EasyAlign! is the right-justification version.)
|
|
|
|
| Mode | Command |
|
|
| ------------------------- | ------------------------------------------- |
|
|
| Interactive mode | :EasyAlign |
|
|
| Using predefined rules | :EasyAlign [FIELD#] DELIMITER_KEY [OPTIONS] |
|
|
| Using regular expressions | :EasyAlign [FIELD#] /REGEXP/ [OPTIONS] |
|
|
|
|
|
|
Interactive mode
|
|
-------------------------------------------------------------------------
|
|
|
|
The command 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 of text 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
|
|
|
|
|
|
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 in Vim dictionary
|
|
format.
|
|
|
|
- :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 are as follows.
|
|
|
|
| Atrribute | Type | Default |
|
|
| ---------------- | ---------------- | --------------------- |
|
|
| left_margin | number or string | 0 |
|
|
| right_margin | number or string | 0 |
|
|
| stick_to_left | boolean | 0 |
|
|
| delimiter_align | string | 'r' |
|
|
| ignore_unmatched | boolean | 1 |
|
|
| ignores | array | ['String', 'Comment'] |
|
|
| indentation | string | 'k' |
|
|
|
|
|
|
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 either defining global `g:easy_align_ignores`
|
|
array,
|
|
|
|
" Ignore nothing!
|
|
let g:easy_align_ignores = []
|
|
|
|
or providing 'ignores' option directly to :EasyAlign command
|
|
|
|
:EasyAlign:{'is':[]}
|
|
|
|
Then you get,
|
|
|
|
{
|
|
# Quantity of apples: 1
|
|
apple: 1,
|
|
# Quantity of bananas: 2
|
|
bananas: 2,
|
|
# Quantity of grape: fruits: 3
|
|
'grape: fruits': 3
|
|
}
|
|
|
|
|
|
Ignoring 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.
|
|
|
|
One way is to set the global `g:easy_align_ignore_unmatched` variable to 0.
|
|
|
|
let g:easy_align_ignore_unmatched = 0
|
|
|
|
Or in non-interactive mode, you can provide 'ignore_unmatched' option to
|
|
`:EasyAlign` command as follows.
|
|
|
|
:EasyAlign:{'iu':0}
|
|
|
|
|
|
Then we get,
|
|
|
|
{
|
|
apple: proc {
|
|
this_line_does_not_have_a_colon
|
|
},
|
|
bananas: 2,
|
|
grapefruits: 3
|
|
}
|
|
|
|
|
|
Aligning delimiters of different lengths *g:easy_align_delimiter_align*
|
|
-------------------------------------------------------------------------
|
|
|
|
Global `g:easy_align_delimiter_align` option and rule-wise/command-wise
|
|
'delimiter_align' option determines how matched delimiters of different
|
|
lengths are aligned.
|
|
|
|
apple = 1
|
|
banana += apple
|
|
cake ||= banana
|
|
|
|
By default, delimiters are right-aligned as follows.
|
|
|
|
apple = 1
|
|
banana += apple
|
|
cake ||= banana
|
|
|
|
However, with ':EasyAlign={'da':l}', delimiters are left-aligned.
|
|
|
|
apple = 1
|
|
banana += apple
|
|
cake ||= banana
|
|
|
|
And on ':EasyAlign={'da':c}', center-aligned.
|
|
|
|
apple = 1
|
|
banana += apple
|
|
cake ||= banana
|
|
|
|
|
|
Adjusting indentation *g:easy_align_indentation*
|
|
-------------------------------------------------------------------------
|
|
|
|
By default :EasyAlign command keeps the original indentation of the lines.
|
|
But then again we have 'indentation' option. See the following example.
|
|
|
|
# Lines with different indentation
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
# Default: _k_eep the original indentation
|
|
# :EasyAlign=
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
# Use the _s_hallowest indentation among the lines
|
|
# :EasyAlign={'idt':s}
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
# Use the _d_eepest indentation among the lines
|
|
# :EasyAlign={'idt':d}
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
# Indentation: _n_one
|
|
# :EasyAlign={'idt':n}
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
Notice that 'idt' is fuzzy-matched to 'indentation'.
|
|
|
|
|
|
Extending alignment rules *g:easy_align_delimiters*
|
|
-------------------------------------------------------------------------
|
|
|
|
Although the default rules should cover the most of the use cases,
|
|
you can extend the rules by setting a dictionary named
|
|
`g:easy_align_delimiters`.
|
|
|
|
let g:easy_align_delimiters = {
|
|
\ '>': { 'pattern': '>>\|=>\|>' },
|
|
\ '/': { 'pattern': '//\+\|/\*\|\*/', 'ignores': ['String'] },
|
|
\ '#': { 'pattern': '#\+', 'ignores': ['String'] },
|
|
\ ']': {
|
|
\ 'pattern': '[\[\]]',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0,
|
|
\ 'stick_to_left': 0
|
|
\ },
|
|
\ ')': {
|
|
\ 'pattern': '[()]',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0,
|
|
\ 'stick_to_left': 0
|
|
\ }
|
|
\ }
|
|
|
|
|