mirror of
https://github.com/junegunn/vim-easy-align.git
synced 2025-11-12 03:43:48 -05:00
991 lines
40 KiB
Plaintext
991 lines
40 KiB
Plaintext
easy-align.txt vim-easy-align Last change: December 22 2013
|
|
|
|
VIM-EASY-ALIGN - TABLE OF CONTENTS *easyalign* *easy-align* *easy-align-toc*
|
|
==============================================================================
|
|
|
|
Demo |easy-align-1|
|
|
Features |easy-align-2|
|
|
"I already have a similar one. Should I switch?" |easy-align-2-1|
|
|
Installation |easy-align-3|
|
|
TLDR - One-minute guide |easy-align-4|
|
|
Usage |easy-align-5|
|
|
Concept of alignment rule |easy-align-5-1|
|
|
Interactive mode |easy-align-5-2|
|
|
Example command sequences |easy-align-5-2-1|
|
|
Using regular expressions |easy-align-5-2-2|
|
|
Alignment options in interactive mode |easy-align-5-2-3|
|
|
EasyAlign as Vim operator |easy-align-5-3|
|
|
Live interactive mode |easy-align-5-4|
|
|
Using EasyAlign in command line |easy-align-5-5|
|
|
Partial alignment in blockwise-visual mode |easy-align-5-6|
|
|
Alignment options |easy-align-6|
|
|
List of options |easy-align-6-1|
|
|
Filtering lines |easy-align-6-2|
|
|
Examples |easy-align-6-2-1|
|
|
Ignoring delimiters in comments or strings |easy-align-6-3|
|
|
Ignoring unmatched lines |easy-align-6-4|
|
|
Aligning delimiters of different lengths |easy-align-6-5|
|
|
Adjusting indentation |easy-align-6-6|
|
|
Alignments over multiple occurrences of delimiters |easy-align-6-7|
|
|
Extending alignment rules |easy-align-6-8|
|
|
Examples |easy-align-6-8-1|
|
|
Other options |easy-align-7|
|
|
Disabling &foldmethod during alignment |easy-align-7-1|
|
|
Left/right/center mode switch in interactive mode |easy-align-7-2|
|
|
Advanced examples and use cases |easy-align-8|
|
|
Related work |easy-align-9|
|
|
Ease of use |easy-align-9-1|
|
|
Clean |easy-align-9-2|
|
|
Optimized for code editing |easy-align-9-3|
|
|
Thoroughly tested |easy-align-9-4|
|
|
"Okay. So should I switch?" |easy-align-9-5|
|
|
Author |easy-align-10|
|
|
License |easy-align-11|
|
|
|
|
|
|
|
|
|
|
VIM-EASY-ALIGN *vim-easy-align*
|
|
==============================================================================
|
|
|
|
A simple, easy-to-use Vim alignment plugin.
|
|
|
|
|
|
*easy-align-1*
|
|
DEMO *easy-align-demo*
|
|
==============================================================================
|
|
|
|
Screencast: https://raw.github.com/junegunn/i/master/vim-easy-align.gif
|
|
|
|
(Too fast? Slower GIF is {here}{1})
|
|
|
|
{1} https://raw.github.com/junegunn/i/master/vim-easy-align-slow.gif
|
|
|
|
|
|
*easy-align-2*
|
|
FEATURES *easy-align-features*
|
|
==============================================================================
|
|
|
|
- Easy to use
|
|
- Comes with a predefined set of alignment rules
|
|
- Provides a fast and intuitive interface
|
|
- Extensible
|
|
- You can define your own rules
|
|
- Supports arbitrary regular expressions
|
|
- Optimized for code editing
|
|
- Takes advantage of syntax highlighting feature to avoid unwanted alignments
|
|
|
|
|
|
< "I already have a similar one. Should I switch?" >__________________________~
|
|
*easy-align-i-already-have-a-similar-one-should-i-switch*
|
|
*easy-align-2-1*
|
|
|
|
Maybe or maybe not. See related work (|easy-align-related-work|) section.
|
|
|
|
|
|
*easy-align-3*
|
|
INSTALLATION *easy-align-installation*
|
|
==============================================================================
|
|
|
|
Either {download zip file}{2} and extract in ~/.vim or {use}{3} {your}{4}
|
|
{favorite}{5} {plugin}{6} {manager}{7}.
|
|
|
|
{2} http://www.vim.org/scripts/script.php?script_id=4520
|
|
{3} https://github.com/tpope/vim-pathogen
|
|
{4} https://github.com/gmarik/vundle
|
|
{5} https://github.com/junegunn/vim-plug
|
|
{6} https://github.com/Shougo/neobundle.vim
|
|
{7} https://github.com/MarcWeber/vim-addon-manager
|
|
|
|
- {Pathogen}{3}
|
|
- `git clone https://github.com/junegunn/vim-easy-align.git ~/.vim/bundle/vim-easy-align`
|
|
- {Vundle}{4}
|
|
- Add `Bundle 'junegunn/vim-easy-align'` to .vimrc
|
|
- Run `:BundleInstall`
|
|
- {NeoBundle}{6}
|
|
- Add `NeoBundle 'junegunn/vim-easy-align'` to .vimrc
|
|
- Run `:NeoBundleInstall`
|
|
- {vim-plug}{5}
|
|
- Add `Plug 'junegunn/vim-easy-align'` to .vimrc
|
|
- Run `:PlugInstall`
|
|
|
|
|
|
*easy-align-4*
|
|
TLDR - ONE-MINUTE GUIDE *easy-align-tldr-one-minute-guide*
|
|
==============================================================================
|
|
|
|
Add the following mappings to your .vimrc.
|
|
>
|
|
" Start interactive EasyAlign in visual mode
|
|
vmap <Enter> <Plug>(EasyAlign)
|
|
|
|
" Start interactive EasyAlign with a Vim movement
|
|
nmap <Leader>a <Plug>(EasyAlign)
|
|
<
|
|
And with the following lines of text,
|
|
>
|
|
apple =red
|
|
grass+=green
|
|
sky-= blue
|
|
<
|
|
try these commands:
|
|
|
|
- vip<Enter>=
|
|
- `v`isual-select `i`nner `p`aragraph
|
|
- Start EasyAlign command (<Enter>)
|
|
- Align around `=`
|
|
- <Leader>aip=
|
|
- Start EasyAlign command (<Leader>a) for `i`nner `p`aragraph
|
|
- Align around `=`
|
|
|
|
Notice that the commands are repeatable with `.` key if you have installed
|
|
{repeat.vim}{8}. Install {visualrepeat}{9} as well if you want to repeat in
|
|
visual mode. Or you can add the following mapping to your .vimrc.
|
|
|
|
{8} https://github.com/tpope/vim-repeat
|
|
{9} https://github.com/vim-scripts/visualrepeat
|
|
|
|
*<Plug>(EasyAlignRepeat)*
|
|
>
|
|
" Repeat alignment in visual mode with . key
|
|
vmap . <Plug>(EasyAlignRepeat)
|
|
<
|
|
|
|
*easy-align-5*
|
|
USAGE *easy-align-usage*
|
|
==============================================================================
|
|
|
|
*:EasyAlign* *:EasyAlign!*
|
|
|
|
vim-easy-align defines `:EasyAlign` command (and the right-align variant
|
|
`:EasyAlign!`).
|
|
|
|
Mode | Command~
|
|
------------------------- | ------------------------------------------------
|
|
Interactive mode | `:EasyAlign[!] [OPTIONS]`
|
|
Using predefined rules | `:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]`
|
|
Using regular expressions | `:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]`
|
|
Live interactive mode | `:LiveEasyAlign[!] [...]`
|
|
|
|
|
|
< Concept of alignment rule >_________________________________________________~
|
|
*easy-align-concept-of-alignment-rule*
|
|
*easy-align-5-1*
|
|
|
|
An alignment rule is a predefined set of options for common alignment tasks,
|
|
which is identified by a single character, DELIMITER KEY, such as <Space> ,
|
|
`=`, `:`, `.`, `|`, `&`, and `,`.
|
|
|
|
Think of it as a shortcut. Instead of writing regular expression and setting
|
|
several options, you can just type in a single character.
|
|
|
|
|
|
< Interactive mode >__________________________________________________________~
|
|
*easy-align-interactive-mode*
|
|
*easy-align-5-2*
|
|
|
|
The command will go into the interactive mode when no argument is given.
|
|
>
|
|
:EasyAlign
|
|
<
|
|
However, it is strongly advised that you define mappings for triggering it in
|
|
your `.vimrc` as follows. (Of course you can use any key combination as the
|
|
trigger.)
|
|
>
|
|
" For visual mode (e.g. vip<Enter>)
|
|
vmap <Enter> <Plug>(EasyAlign)
|
|
|
|
" For normal mode, with Vim movement (e.g. <Leader>aip)
|
|
nmap <Leader>a <Plug>(EasyAlign)
|
|
<
|
|
The advantages of using the above mappings are two-fold:
|
|
|
|
- They require less keystrokes
|
|
- They make alignments repeatable with {repeat.vim}{8} and {visualrepeat}{9}
|
|
|
|
With the mapping, you can align selected lines of text with only a few
|
|
keystrokes.
|
|
|
|
1. <Enter> key in visual mode, or <Leader>a followed by a Vim movement to start
|
|
interactive EasyAlign command
|
|
2. Optional: Enter keys to select alignment mode (left, right, or center)
|
|
3. Optional: N-th delimiter (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> , `=`, `:`, `.`, `|`, `&`, `,`)
|
|
|
|
Alignment rules for the following delimiters have been defined to meet the most
|
|
needs.
|
|
|
|
Delimiter key | Description/Use cases~
|
|
------------- | --------------------------------------------------------------------
|
|
<Space> | General alignment around whitespaces
|
|
`=` | Operators containing equals sign (`=` , `==,` `!=` , `+=` , `&&=` , ...)
|
|
`:` | Suitable for formatting JSON or YAML
|
|
`.` | Multi-line method chaining
|
|
`,` | Multi-line method arguments
|
|
`&` | LaTeX tables (matches `&` and `\\` )
|
|
<Bar> | Table markdown
|
|
|
|
*g:easy_align_delimiters*
|
|
|
|
You can override these default rules or define your own rules with
|
|
`g:easy_align_delimiters`, which will be described in the later section
|
|
(|easy-align-extending-alignment-rules|).
|
|
|
|
|
|
Example command sequences~
|
|
*easy-align-example-command-sequences*
|
|
*easy-align-5-2-1*
|
|
|
|
With visual map | Description | Equivalent command~
|
|
------------------- | ---------------------------------- | ----------------------
|
|
<Enter><Space> | Around 1st whitespaces | :'<,'>EasyAlign\
|
|
<Enter>2<Space> | Around 2nd whitespaces | :'<,'>EasyAlign2\
|
|
<Enter>-<Space> | Around the last whitespaces | :'<,'>EasyAlign-\
|
|
<Enter>-2<Space> | Around the 2nd to last whitespaces | :'<,'>EasyAlign-2\
|
|
<Enter>: | Around 1st colon (`key: value`) | :'<,'>EasyAlign:
|
|
<Enter><Right>: | Around 1st colon (`key : value`) | :'<,'>EasyAlign:s0l1
|
|
<Enter>= | Around 1st operators with = | :'<,'>EasyAlign=
|
|
<Enter>2= | Around 2nd operators with = | :'<,'>EasyAlign2=
|
|
<Enter>3= | Around 3rd operators with = | :'<,'>EasyAlign3=
|
|
<Enter>*= | Around all operators with = | :'<,'>EasyAlign*=
|
|
<Enter>**= | Left-right alternating around = | :'<,'>EasyAlign**=
|
|
<Enter><Enter>= | Right alignment around 1st = | :'<,'>EasyAlign!=
|
|
<Enter><Enter>**= | Right-left alternating around = | :'<,'>EasyAlign!**=
|
|
|
|
|
|
Using regular expressions~
|
|
*easy-align-using-regular-expressions*
|
|
*easy-align-5-2-2*
|
|
|
|
Instead of finishing the command with a predefined delimiter key, you can type
|
|
in a regular expression after CTRL-/ or CTRL-X key. For example, if you want to
|
|
align text around all occurrences of numbers:
|
|
|
|
- <Enter>
|
|
- `*`
|
|
- CTRL-/ (or CTRL-X on GVim)
|
|
- `[0-9]\+`
|
|
|
|
|
|
Alignment options in interactive mode~
|
|
*easy-align-alignment-options-in-interactive-mode*
|
|
*easy-align-5-2-3*
|
|
|
|
While in interactive mode, you can set alignment options using special shortcut
|
|
keys listed below. The meaning of each option will be described in the
|
|
following sections (|easy-align-alignment-options|).
|
|
|
|
Key | Option | Values~
|
|
--------- | ------------------ | --------------------------------------------------
|
|
CTRL-F | `filter` | Input string (`[gv]/.*/?` )
|
|
CTRL-I | `indentation` | shallow, deep, none, keep
|
|
CTRL-L | `left_margin` | Input number or string
|
|
CTRL-R | `right_margin` | Input number or string
|
|
CTRL-D | `delimiter_align` | left, center, right
|
|
CTRL-U | `ignore_unmatched` | 0, 1
|
|
CTRL-G | `ignore_groups` | [], ['String'], ['Comment'], ['String', 'Comment']
|
|
CTRL-O | `mode_sequence` | Input string (`/[lrc]+\*{0,2}/` )
|
|
<Left> | `stick_to_left` | `{ 'stick_to_left': 1, 'left_margin': 0 }`
|
|
<Right> | `stick_to_left` | `{ 'stick_to_left': 0, 'left_margin': 1 }`
|
|
<Down> | `*_margin` | `{ 'left_margin': 0, 'right_margin': 0 }`
|
|
|
|
*g:easy_align_last_command*
|
|
|
|
After a successful alignment, you can repeat the same operation using the
|
|
repeatable, non-interactive command recorded in `g:easy_align_last_command`.
|
|
>
|
|
:<C-R>=g:easy_align_last_command<Enter><Enter>
|
|
<
|
|
|
|
< EasyAlign as Vim operator >_________________________________________________~
|
|
*easy-align-easyalign-as-vim-operator*
|
|
*easy-align-5-3*
|
|
|
|
*<Plug>(EasyAlign)*
|
|
|
|
With normal-mode map to <Plug>(EasyAlign) , EasyAlign command becomes a Vim
|
|
operator that can be used with any Vim movement.
|
|
>
|
|
nmap <Leader>a <Plug>(EasyAlign)
|
|
<
|
|
Now without going into visual mode, you can align the lines in the paragraph
|
|
with <Leader>aip= , <Leader>aip*| , or <Leader>aip: . And if you have installed
|
|
{repeat.vim}{8} by Tim Pope, the exact alignment can be repeated with `.` key.
|
|
|
|
{8} https://github.com/tpope/vim-repeat
|
|
|
|
|
|
< Live interactive mode >_____________________________________________________~
|
|
*easy-align-live-interactive-mode*
|
|
*easy-align-5-4*
|
|
|
|
If you're performing a complex alignment where multiple options should be
|
|
carefully adjusted, try "live interactive mode" where you can preview the
|
|
result of the alignment on-the-fly as you type in.
|
|
|
|
*:LiveEasyAlign*
|
|
|
|
Live interactive mode can be started with `:LiveEasyAlign` command which takes
|
|
the same parameters as `:EasyAlign`. I suggest you define mappings such as
|
|
follows in addition to the ones for `:EasyAlign` command.
|
|
|
|
*<Plug>(LiveEasyAlign)*
|
|
>
|
|
vmap <Leader><Enter> <Plug>(LiveEasyAlign)
|
|
nmap <Leader><Leader>a <Plug>(LiveEasyAlign)
|
|
<
|
|
In live interactive mode, you have to type in the same delimiter (or CTRL-X on
|
|
regular expression) again to finalize the alignment. This allows you to preview
|
|
the result of the alignment and freely change the delimiter using backspace key
|
|
without leaving the interactive mode.
|
|
|
|
|
|
< Using EasyAlign in command line >___________________________________________~
|
|
*easy-align-using-easyalign-in-command-line*
|
|
*easy-align-5-5*
|
|
|
|
Instead of going into the interactive mode, you can just type in arguments to
|
|
`:EasyAlign` command.
|
|
>
|
|
" Using predefined alignment rules
|
|
:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]
|
|
|
|
" Using arbitrary regular expressions
|
|
:EasyAlign[!] [N-th] /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 **/[:;]\+/`
|
|
|
|
You can also provide a number of alignment options, which will be discussed in
|
|
detail later (|easy-align-alignment-options|), to EasyAlign command in Vim
|
|
dictionary format.
|
|
|
|
- `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }`
|
|
|
|
Which means that the matched delimiter should be positioned right next to the
|
|
preceding token, without margin on the left. So we get:
|
|
>
|
|
apple;: banana:: cake
|
|
data;; exchange:; format
|
|
<
|
|
Option names are fuzzy-matched, so you can write as follows:
|
|
|
|
- `:EasyAlign * /[:;]\+/ { 'stl': 1, 'l': 0 }`
|
|
|
|
You can even omit spaces between the arguments, so concisely (or cryptically):
|
|
|
|
- `:EasyAlign*/[:;]\+/{'s':1,'l':0}`
|
|
|
|
Nice. But let's make it even shorter. Option values can be written in shorthand
|
|
notation.
|
|
|
|
- `:EasyAlign*/[:;]\+/s1l0`
|
|
|
|
The following table summarizes the shorthand notation.
|
|
|
|
Option | Expression~
|
|
------------------ | ----------
|
|
`filter` | `[gv]/.*/`
|
|
`left_margin` | `l[0-9]+`
|
|
`right_margin` | `r[0-9]+`
|
|
`stick_to_left` | `s[01]`
|
|
`ignore_unmatched` | `iu[01]`
|
|
`ignore_groups` | `ig\[.*\]`
|
|
`delimiter_align` | `d[lrc]`
|
|
`mode_sequence` | `m[lrc*]*`
|
|
`indentation` | `i[ksdn]`
|
|
|
|
For your information, the same thing can be done in the interactive mode as
|
|
well with the following key combination.
|
|
|
|
- <Enter>
|
|
- `*`
|
|
- <Left>
|
|
- CTRL-/ (or CTRL-X on GVim)
|
|
- `[:;]\+`
|
|
|
|
|
|
< Partial alignment in blockwise-visual mode >________________________________~
|
|
*easy-align-partial-alignment-in-blockwise-visual-mode*
|
|
*easy-align-5-6*
|
|
|
|
In blockwise-visual mode (CTRL-V), EasyAlign command aligns only the selected
|
|
text in the block, instead of the whole lines in the range.
|
|
|
|
Consider the following case where you want to align text around `=>` operators.
|
|
>
|
|
my_hash = { :a => 1,
|
|
:aa => 2,
|
|
:aaa => 3 }
|
|
<
|
|
In non-blockwise visual mode (`v` / `V`), <Enter>= won't work since the
|
|
assignment operator in the first line gets in the way. So we instead enter
|
|
blockwise-visual mode (CTRL-V), and select the text around `=>` operators,
|
|
then press <Enter>= .
|
|
>
|
|
my_hash = { :a => 1,
|
|
:aa => 2,
|
|
:aaa => 3 }
|
|
<
|
|
However, in this case, we don't really need blockwise visual mode since the
|
|
same can be easily done using the negative N-th parameter: <Enter>-=
|
|
|
|
|
|
*easy-align-6*
|
|
ALIGNMENT OPTIONS *easy-align-alignment-options*
|
|
==============================================================================
|
|
|
|
|
|
< List of options >___________________________________________________________~
|
|
*easy-align-list-of-options*
|
|
*easy-align-6-1*
|
|
|
|
Option | Type | Default | Description~
|
|
------------------ | ------- | --------------------- | -------------------------------------------------------
|
|
`filter` | string | | Line filtering expression: `g/../` or `v/../`
|
|
`left_margin` | number | 1 | Number of spaces to attach before delimiter
|
|
`left_margin` | string | `' '` | String to attach before delimiter
|
|
`right_margin` | number | 1 | Number of spaces to attach after delimiter
|
|
`right_margin` | string | `' '` | String to attach after delimiter
|
|
`stick_to_left` | boolean | 0 | Whether to position delimiter on the left-side
|
|
`ignore_groups` | list | ['String', 'Comment'] | Delimiters in these syntax highlight groups are ignored
|
|
`ignore_unmatched` | boolean | 1 | Whether to ignore lines without matching delimiter
|
|
`indentation` | string | `k` | Indentation method (keep, deep, shallow, none)
|
|
`delimiter_align` | string | `r` | Determines how to align delimiters of different lengths
|
|
`mode_sequence` | string | | Alignment modes for multiple occurrences of delimiters
|
|
|
|
There are 4 ways to set alignment options (from lowest precedence to highest):
|
|
|
|
1. Some option values can be set with corresponding global variables
|
|
2. Option values can be specified in the definition of each alignment rule
|
|
3. Option values can be given as arguments to `:EasyAlign` command
|
|
4. Option values can be set in interactive mode using special shortcut keys
|
|
|
|
*g:easy_align_ignore_groups* *g:easy_align_ignore_unmatched*
|
|
*g:easy_align_indentation* *g:easy_align_delimiter_align*
|
|
|
|
Option name | Shortcut key | Abbreviated | Global variable~
|
|
------------------ | ------------------- | ----------- | -------------------------------
|
|
`filter` | CTRL-F | `[gv]/.*/` |
|
|
`left_margin` | CTRL-L | `l[0-9]+` |
|
|
`right_margin` | CTRL-R | `r[0-9]+` |
|
|
`stick_to_left` | <Left> , <Right> | `s[01]` |
|
|
`ignore_groups` | CTRL-G | `ig\[.*\]` | `g:easy_align_ignore_groups`
|
|
`ignore_unmatched` | CTRL-U | `iu[01]` | `g:easy_align_ignore_unmatched`
|
|
`indentation` | CTRL-I | `i[ksdn]` | `g:easy_align_indentation`
|
|
`delimiter_align` | CTRL-D | `d[lrc]` | `g:easy_align_delimiter_align`
|
|
`mode_sequence` | CTRL-O | `m[lrc*]*` |
|
|
|
|
|
|
< Filtering lines >___________________________________________________________~
|
|
*easy-align-filtering-lines*
|
|
*easy-align-6-2*
|
|
|
|
With `filter` option, you can align lines that only match or do not match a
|
|
given pattern. There are several ways to set the pattern.
|
|
|
|
1. Press CTRL-F in interactive mode and input `g/pat/` or `v/pat/`
|
|
2. In command-line, it can be written in dictionary format: `{'filter': 'g/pat/'}`
|
|
3. Or in shorthand notation: `g/pat/` or `v/pat/`
|
|
|
|
(You don't need to escape '/'s in the regular expression)
|
|
|
|
|
|
Examples~
|
|
*easy-align-examples*
|
|
*easy-align-6-2-1*
|
|
>
|
|
" Start interactive mode with filter option set to g/hello/
|
|
EasyAlign g/hello/
|
|
|
|
" Start live interactive mode with filter option set to v/goodbye/
|
|
LiveEasyAlign v/goodbye/
|
|
|
|
" Align the lines with 'hi' around the first colons
|
|
EasyAlign:g/hi/
|
|
<
|
|
|
|
< Ignoring delimiters in comments or strings >________________________________~
|
|
*easy-align-ignoring-delimiters-in-comments-or-strings*
|
|
*easy-align-6-3*
|
|
|
|
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_ignore_groups = ['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>: (or `:EasyAlign:`)
|
|
>
|
|
{
|
|
# 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 using one of these 4 methods.
|
|
|
|
1. Press CTRL-G in interactive mode to switch groups
|
|
2. Define global `g:easy_align_ignore_groups` list
|
|
3. Define a custom rule in `g:easy_align_delimiters` with `ignore_groups` option
|
|
4. Provide `ignore_groups` option to `:EasyAlign` command. e.g. `:EasyAlign:ig[]`
|
|
|
|
For example if you set `ignore_groups` option to be an empty list, you get
|
|
>
|
|
{
|
|
# Quantity of apples: 1
|
|
apple: 1,
|
|
# Quantity of bananas: 2
|
|
bananas: 2,
|
|
# Quantity of grape: fruits: 3
|
|
'grape: fruits': 3
|
|
}
|
|
<
|
|
Satisfied?
|
|
|
|
|
|
< Ignoring unmatched lines >__________________________________________________~
|
|
*easy-align-ignoring-unmatched-lines*
|
|
*easy-align-6-4*
|
|
|
|
`ignore_unmatched` option determines how EasyAlign command processes lines that
|
|
do not have N-th delimiter.
|
|
|
|
1. In left-alignment mode, they are ignored
|
|
2. In right or center-alignment mode, they are not ignored, and the last tokens
|
|
from those lines are aligned as well as if there is an invisible trailing
|
|
delimiter at the end of each line
|
|
3. If `ignore_unmatched` is 1, they are ignored regardless of the alignment mode
|
|
4. If `ignore_unmatched` is 0, they are not ignored regardless of the mode
|
|
|
|
Let's take an example. When we align the following code block around the (1st)
|
|
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, we can override this default behavior by setting `ignore_unmatched`
|
|
option to zero using one of the following methods.
|
|
|
|
1. Press CTRL-U in interactive mode to toggle `ignore_unmatched` option
|
|
2. Set the global `g:easy_align_ignore_unmatched` variable to 0
|
|
3. Define a custom alignment rule with `ignore_unmatched` option set to 0
|
|
4. Provide `ignore_unmatched` option to `:EasyAlign` command. e.g.
|
|
`:EasyAlign:iu0`
|
|
|
|
Then we get,
|
|
>
|
|
{
|
|
apple: proc {
|
|
this_line_does_not_have_a_colon
|
|
},
|
|
bananas: 2,
|
|
grapefruits: 3
|
|
}
|
|
<
|
|
|
|
< Aligning delimiters of different lengths >__________________________________~
|
|
*easy-align-aligning-delimiters-of-different-lengths*
|
|
*easy-align-6-5*
|
|
|
|
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=dl`, delimiters are left-aligned.
|
|
>
|
|
apple = 1
|
|
banana += apple
|
|
cake ||= banana
|
|
<
|
|
And on `:EasyAlign=dc`, center-aligned.
|
|
>
|
|
apple = 1
|
|
banana += apple
|
|
cake ||= banana
|
|
<
|
|
In interactive mode, you can change the option value with CTRL-D key.
|
|
|
|
|
|
< Adjusting indentation >_____________________________________________________~
|
|
*easy-align-adjusting-indentation*
|
|
*easy-align-6-6*
|
|
|
|
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=is
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
# Use the _d_eepest indentation among the lines
|
|
# :EasyAlign=id
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
|
|
# Indentation: _n_one
|
|
# :EasyAlign=in
|
|
apple = 1
|
|
banana = 2
|
|
cake = 3
|
|
daisy = 4
|
|
eggplant = 5
|
|
<
|
|
Notice that `idt` is fuzzy-matched to `indentation`.
|
|
|
|
In interactive mode, you can change the option value with CTRL-I key.
|
|
|
|
|
|
< Alignments over multiple occurrences of delimiters >________________________~
|
|
*easy-align-alignments-over-multiple-occurrences-of-delimiters*
|
|
*easy-align-6-7*
|
|
|
|
As stated above, "N-th" parameter is used to target specific occurrences of the
|
|
delimiter when it appears multiple times in each line.
|
|
|
|
To recap:
|
|
>
|
|
" Left-alignment around the FIRST occurrences of delimiters
|
|
:EasyAlign =
|
|
|
|
" Left-alignment around the SECOND occurrences of delimiters
|
|
:EasyAlign 2=
|
|
|
|
" Left-alignment around the LAST occurrences of delimiters
|
|
:EasyAlign -=
|
|
|
|
" Left-alignment around ALL occurrences of delimiters
|
|
:EasyAlign *=
|
|
|
|
" Left-right ALTERNATING alignment around all occurrences of delimiters
|
|
:EasyAlign **=
|
|
|
|
" Right-left ALTERNATING alignment around all occurrences of delimiters
|
|
:EasyAlign! **=
|
|
<
|
|
In addition to these, you can fine-tune alignments over multiple occurrences of
|
|
the delimiters with 'mode_sequence' option. (The option can also be set in
|
|
interactive mode with the special key CTRL-O)
|
|
>
|
|
" Left alignment over the first two occurrences of delimiters
|
|
:EasyAlign = { 'mode_sequence': 'll' }
|
|
|
|
" Right, left, center alignment over the 1st to 3rd occurrences of delimiters
|
|
:EasyAlign = { 'm': 'rlc' }
|
|
|
|
" Using shorthand notation
|
|
:EasyAlign = mrlc
|
|
|
|
" Right, left, center alignment over the 2nd to 4th occurrences of delimiters
|
|
:EasyAlign 2=mrlc
|
|
|
|
" (*) Repeating alignments (default: l, r, or c)
|
|
" Right, left, center, center, center, center, ...
|
|
:EasyAlign *=mrlc
|
|
|
|
" (**) Alternating alignments (default: lr or rl)
|
|
" Right, left, center, right, left, center, ...
|
|
:EasyAlign **=mrlc
|
|
|
|
" Right, left, center, center, center, ... repeating alignment
|
|
" over the 3rd to the last occurrences of delimiters
|
|
:EasyAlign 3=mrlc*
|
|
|
|
" Right, left, center, right, left, center, ... alternating alignment
|
|
" over the 3rd to the last occurrences of delimiters
|
|
:EasyAlign 3=mrlc**
|
|
<
|
|
|
|
< Extending alignment rules >_________________________________________________~
|
|
*easy-align-extending-alignment-rules*
|
|
*easy-align-6-8*
|
|
|
|
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`.
|
|
|
|
You may refer to the definitions of the default alignment rules {here}{10}.
|
|
|
|
{10} https://github.com/junegunn/vim-easy-align/blob/2.9.0/autoload/easy_align.vim#L29
|
|
|
|
|
|
Examples~
|
|
*easy-align-examples-2*
|
|
*easy-align-6-8-1*
|
|
>
|
|
let g:easy_align_delimiters = {
|
|
\ '>': { 'pattern': '>>\|=>\|>' },
|
|
\ '/': { 'pattern': '//\+\|/\*\|\*/', 'ignore_groups': ['String'] },
|
|
\ '#': { 'pattern': '#\+', 'ignore_groups': ['String'], 'delimiter_align': 'l' },
|
|
\ ']': {
|
|
\ 'pattern': '[[\]]',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0,
|
|
\ 'stick_to_left': 0
|
|
\ },
|
|
\ ')': {
|
|
\ 'pattern': '[()]',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0,
|
|
\ 'stick_to_left': 0
|
|
\ },
|
|
\ 'd': {
|
|
\ 'pattern': ' \(\S\+\s*[;=]\)\@=',
|
|
\ 'left_margin': 0,
|
|
\ 'right_margin': 0
|
|
\ }
|
|
\ }
|
|
<
|
|
|
|
*easy-align-7*
|
|
OTHER OPTIONS *easy-align-other-options*
|
|
==============================================================================
|
|
|
|
|
|
< Disabling &foldmethod during alignment >____________________________________~
|
|
*easy-align-disabling-foldmethod-during-alignment*
|
|
*easy-align-7-1*
|
|
|
|
*g:easy_align_bypass_fold*
|
|
|
|
{It is reported}{11} that 'foldmethod' value of `expr` or `syntax` can
|
|
significantly slow down the alignment when editing a large, complex file with
|
|
many folds. To alleviate this issue, EasyAlign provides an option to
|
|
temporarily set 'foldmethod' to `manual` during the alignment task. In order to
|
|
enable this feature, set `g:easy_align_bypass_fold` switch to 1.
|
|
|
|
{11} https://github.com/junegunn/vim-easy-align/issues/14
|
|
>
|
|
let g:easy_align_bypass_fold = 1
|
|
<
|
|
|
|
< Left/right/center mode switch in interactive mode >_________________________~
|
|
*easy-align-left-right-center-mode-switch-in-interactive-mode*
|
|
*easy-align-7-2*
|
|
|
|
In interactive mode, you can choose the alignment mode you want by pressing
|
|
enter keys. The non-bang command, `:EasyAlign` starts in left-alignment mode
|
|
and changes to right and center mode as you press enter keys, while the bang
|
|
version first starts in right-alignment mode.
|
|
|
|
- `:EasyAlign`
|
|
- Left, Right, Center
|
|
- `:EasyAlign!`
|
|
- Right, Left, Center
|
|
|
|
If you do not prefer this default mode transition, you can define your own
|
|
settings as follows.
|
|
|
|
*g:easy_align_interactive_modes*
|
|
*g:easy_align_bang_interactive_modes*
|
|
>
|
|
let g:easy_align_interactive_modes = ['l', 'r']
|
|
let g:easy_align_bang_interactive_modes = ['c', 'r']
|
|
<
|
|
|
|
*easy-align-8*
|
|
ADVANCED EXAMPLES AND USE CASES *easy-align-advanced-examples-and-use-cases*
|
|
==============================================================================
|
|
|
|
See {EXAMPLES.md}{12} for more examples.
|
|
|
|
{12} https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md
|
|
|
|
|
|
*easy-align-9*
|
|
RELATED WORK *easy-align-related-work*
|
|
==============================================================================
|
|
|
|
There are two well-known plugins with the same goal as that of vim-easy-align.
|
|
|
|
- {DrChip's Alignment Tool for Vim}{13} (herein will be referred to as "Align")
|
|
- {Tabular}{14}
|
|
|
|
Both are great plugins with very large user bases. I actually had been a
|
|
Tabular user for a couple of years before I finally made up my mind to roll out
|
|
my own.
|
|
|
|
So why would someone choose vim-easy-align over those two?
|
|
|
|
Feature-by-feature comparison I believe is not quite useful, since a typical
|
|
user will end up using only a small subset of the features. So I will mention
|
|
just a few core benefits of vim-easy-align.
|
|
|
|
|
|
< Ease of use >_______________________________________________________________~
|
|
*easy-align-ease-of-use*
|
|
*easy-align-9-1*
|
|
|
|
As the name implies, vim-easy-align is easier to use. Its interactive mode
|
|
allows you to achieve what you want with just a few keystrokes. The key
|
|
sequence is mnemonic, so it's easy to remember and execute. It even feels like
|
|
a native Vim command!
|
|
|
|
- Right-align: <Enter><Enter>
|
|
- around the second occurrences: `2`
|
|
- of whitespaces: <Space>
|
|
|
|
For the simplest cases, Tabular and Align are also easy to use. But sooner or
|
|
later, you will find yourself scratching your head, trying to come up with some
|
|
complex regular expressions.
|
|
|
|
"How am I going to align the third to the last word in each line to the right
|
|
without affecting the ones before it?"
|
|
|
|
|
|
< Clean >_____________________________________________________________________~
|
|
*easy-align-clean*
|
|
*easy-align-9-2*
|
|
|
|
vim-easy-align doesn't clutter your workspace with mappings and global
|
|
variables. All you would need is a single mapping to the interactive EasyAlign
|
|
command, and even that is totally up to you.
|
|
|
|
|
|
< Optimized for code editing >________________________________________________~
|
|
*easy-align-optimized-for-code-editing*
|
|
*easy-align-9-3*
|
|
|
|
vim-easy-align by default performs syntax-aware alignment, which is invaluable
|
|
when editing codes.
|
|
|
|
Try to come up with a regular expression to correctly format the following code
|
|
snippet. With vim-easy-align under default configuration and a mapping, it can
|
|
be done with just two keystrokes: <Enter>:
|
|
>
|
|
var jdbc = {
|
|
// JDBC driver for MySQL database:
|
|
driver: "com.mysql.jdbc.Driver",
|
|
/* JDBC URL for the connection (jdbc:mysql://HOSTNAME/DATABASE) */
|
|
url: 'jdbc:mysql://localhost/test',
|
|
database: "test",
|
|
"user:pass":"r00t:pa55"
|
|
};
|
|
<
|
|
(To be fair, Align also can be configured to consider syntax highlighting with
|
|
`g:AlignSkip` function reference which should point to a custom function that
|
|
looks up the syntax group of a character on a certain position)
|
|
|
|
|
|
< Thoroughly tested >_________________________________________________________~
|
|
*easy-align-thoroughly-tested*
|
|
*easy-align-9-4*
|
|
|
|
Virtually every aspect of vim-easy-align is being tested with a comprehensive
|
|
set of test cases using {Vader.vim}{15}.
|
|
|
|
{15} https://github.com/junegunn/vader.vim
|
|
|
|
|
|
< "Okay. So should I switch?" >_______________________________________________~
|
|
*easy-align-okay-so-should-i-switch*
|
|
*easy-align-9-5*
|
|
|
|
Maybe, but I can't really say. I have no ambition to make vim-easy-align an
|
|
absolute superior to the others. For some cases, vim-easy-align works better
|
|
than the others, but for some other cases, Tabular or Align.vim might be a
|
|
better choice.
|
|
|
|
So try it yourself and see if it works for you!
|
|
|
|
|
|
*easy-align-10*
|
|
AUTHOR *easy-align-author*
|
|
==============================================================================
|
|
|
|
{Junegunn Choi}{16}
|
|
|
|
{16} https://github.com/junegunn
|
|
|
|
|
|
*easy-align-11*
|
|
LICENSE *easy-align-license*
|
|
==============================================================================
|
|
|
|
MIT
|
|
|
|
==============================================================================
|
|
vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap:
|