892 lines
36 KiB
Plaintext
892 lines
36 KiB
Plaintext
easy-align.txt easy-align Last change: December 14 2014
|
|
EASY-ALIGN - TABLE OF CONTENTS *easyalign* *easy-align* *easy-align-toc*
|
|
==============================================================================
|
|
|
|
vim-easy-align
|
|
Demo |easy-align-1|
|
|
Features |easy-align-2|
|
|
Installation |easy-align-3|
|
|
TLDR - One-minute guide |easy-align-4|
|
|
Usage |easy-align-5|
|
|
Concept of alignment rule |easy-align-5-1|
|
|
Execution models |easy-align-5-2|
|
|
1. Using <Plug> mappings |easy-align-5-2-1|
|
|
2. Using :EasyAlign command |easy-align-5-2-2|
|
|
Interactive mode |easy-align-5-3|
|
|
Predefined alignment rules |easy-align-5-3-1|
|
|
Examples |easy-align-5-3-2|
|
|
Using regular expressions |easy-align-5-3-3|
|
|
Alignment options in interactive mode |easy-align-5-3-4|
|
|
Live interactive mode |easy-align-5-4|
|
|
Non-interactive mode |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|
|
|
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.githubusercontent.com/junegunn/i/master/vim-easy-align.gif
|
|
|
|
(Too fast? Slower GIF is {here}{1})
|
|
|
|
{1} https://raw.githubusercontent.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
|
|
|
|
|
|
*easy-align-3*
|
|
INSTALLATION *easy-align-installation*
|
|
==============================================================================
|
|
|
|
Use your favorite plugin manager.
|
|
|
|
Using {vim-plug}{2}:
|
|
>
|
|
Plug 'junegunn/vim-easy-align'
|
|
<
|
|
{2} https://github.com/junegunn/vim-plug
|
|
|
|
|
|
*easy-align-4*
|
|
TLDR - ONE-MINUTE GUIDE *easy-align-tldr-one-minute-guide*
|
|
==============================================================================
|
|
|
|
Add the following mappings to your .vimrc.
|
|
|
|
*<Plug>(EasyAlign)*
|
|
>
|
|
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
|
|
vmap <Enter> <Plug>(EasyAlign)
|
|
|
|
" Start interactive EasyAlign for a motion/text object (e.g. gaip)
|
|
nmap ga <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 `=`
|
|
- `gaip=`
|
|
- Start EasyAlign command (`ga`) for `i`nner `p`aragraph
|
|
- Align around `=`
|
|
|
|
Notice that the commands are repeatable with `.` key if you have installed
|
|
{repeat.vim}{3}. Install {visualrepeat}{4} as well if you want to repeat in
|
|
visual mode.
|
|
|
|
{3} https://github.com/tpope/vim-repeat
|
|
{4} https://github.com/vim-scripts/visualrepeat
|
|
|
|
|
|
*easy-align-5*
|
|
USAGE *easy-align-usage*
|
|
==============================================================================
|
|
|
|
|
|
< Concept of alignment rule >_________________________________________________~
|
|
*easy-align-concept-of-alignment-rule*
|
|
*easy-align-5-1*
|
|
|
|
Though easy-align can align lines of text around any delimiter, it provides
|
|
shortcuts for the most common use cases with the concept of "alignment rule".
|
|
|
|
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.
|
|
|
|
|
|
< Execution models >__________________________________________________________~
|
|
*easy-align-execution-models*
|
|
*easy-align-5-2*
|
|
|
|
There are two ways to use easy-align.
|
|
|
|
|
|
1. Using <Plug> mappings~
|
|
*easy-align-1-using-plug-mappings*
|
|
*easy-align-5-2-1*
|
|
|
|
The recommended method is to use <Plug> mappings as described earlier.
|
|
|
|
*<Plug>(LiveEasyAlign)*
|
|
|
|
----------------------+--------+-----------------------------------------------------
|
|
Mapping | Mode | Description ~
|
|
----------------------+--------+-----------------------------------------------------
|
|
<Plug>(EasyAlign) | normal | Start interactive mode for a motion/text object
|
|
<Plug>(EasyAlign) | visual | Start interactive mode for the selection
|
|
<Plug>(LiveEasyAlign) | normal | Start live-interactive mode for a motion/text object
|
|
<Plug>(LiveEasyAlign) | visual | Start live-interactive mode for the selection
|
|
----------------------+--------+-----------------------------------------------------
|
|
|
|
|
|
2. Using :EasyAlign command~
|
|
*easy-align-2-using-easyalign-command*
|
|
*easy-align-5-2-2*
|
|
|
|
*:EasyAlign*
|
|
|
|
If you prefer command-line or do not want to start interactive mode, you can
|
|
use `:EasyAlign` command instead.
|
|
|
|
*:LiveEasyAlign*
|
|
|
|
-------------------------------------------+-----------------------------------------------
|
|
Mode | Command ~
|
|
-------------------------------------------+-----------------------------------------------
|
|
Interactive mode | `:EasyAlign[!] [OPTIONS]`
|
|
Live interactive mode | `:LiveEasyAlign[!] [...]`
|
|
Non-interactive mode (predefined rules) | `:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]`
|
|
Non-interactive mode (regular expressions) | `:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]`
|
|
-------------------------------------------+-----------------------------------------------
|
|
|
|
|
|
< Interactive mode >__________________________________________________________~
|
|
*easy-align-interactive-mode*
|
|
*easy-align-5-3*
|
|
|
|
The following sections will assume that you have <Plug>(EasyAlign) mappings in
|
|
your .vimrc as below:
|
|
>
|
|
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
|
|
vmap <Enter> <Plug>(EasyAlign)
|
|
|
|
" Start interactive EasyAlign for a motion/text object (e.g. gaip)
|
|
nmap ga <Plug>(EasyAlign)
|
|
<
|
|
With these mappings, you can align text with only a few keystrokes.
|
|
|
|
1. <Enter> key in visual mode, or `ga` followed by a motion or a text object to
|
|
start interactive mode
|
|
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>, `=`, `:`, `.`, `|`, `&`, `#`, `,`)
|
|
|
|
|
|
Predefined alignment rules~
|
|
*easy-align-predefined-alignment-rules*
|
|
*easy-align-5-3-1*
|
|
|
|
--------------+--------------------------------------------------------------------
|
|
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 `\\` )
|
|
`#` | Ruby/Python comments
|
|
`"` | Vim comments
|
|
<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}{5}.
|
|
|
|
{5} https://github.com/junegunn/vim-easy-align#extending-alignment-rules
|
|
|
|
|
|
Examples~
|
|
*easy-align-examples*
|
|
*easy-align-5-3-2*
|
|
|
|
------------------+------------------------------------+--------------------
|
|
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:<l1
|
|
<Enter>= | Around 1st operators with = | :'<,'>EasyAlign=
|
|
<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-3-3*
|
|
|
|
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-X
|
|
- `[0-9]\+`
|
|
|
|
|
|
Alignment options in interactive mode~
|
|
*easy-align-alignment-options-in-interactive-mode*
|
|
*easy-align-5-3-4*
|
|
|
|
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}{6}.
|
|
|
|
--------+--------------------+---------------------------------------------------
|
|
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-A | `align` | 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 }`
|
|
--------+--------------------+---------------------------------------------------
|
|
|
|
{6} https://github.com/junegunn/vim-easy-align#alignment-options
|
|
|
|
|
|
< 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.
|
|
|
|
Live interactive mode can be started with either <Plug>(LiveEasyAlign) map or
|
|
`:LiveEasyAlign` command. Or you can switch to live interactive mode while in
|
|
ordinary interactive mode by pressing CTRL-P. (P for Preview)
|
|
|
|
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.
|
|
|
|
|
|
< Non-interactive mode >______________________________________________________~
|
|
*easy-align-non-interactive-mode*
|
|
*easy-align-5-5*
|
|
|
|
Instead of starting interactive mode, you can use declarative, non-interactive
|
|
`:EasyAlign` command.
|
|
>
|
|
" Using predefined alignment rules
|
|
" :EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]
|
|
:EasyAlign :
|
|
:EasyAlign =
|
|
:EasyAlign *=
|
|
:EasyAlign 3\
|
|
|
|
" Using arbitrary regular expressions
|
|
" :EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]
|
|
:EasyAlign /[:;]\+/
|
|
:EasyAlign 2/[:;]\+/
|
|
:EasyAlign */[:;]\+/
|
|
:EasyAlign **/[:;]\+/
|
|
<
|
|
A command can end with alignment options, {each of which will be discussed in
|
|
detail later}{6}, in Vim dictionary format.
|
|
|
|
- `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }`
|
|
|
|
`stick_to_left` of 1 means that the matched delimiter should be positioned
|
|
right next to the preceding token, and `left_margin` of 0 removes the 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*/[:;]\+/<l0`
|
|
|
|
The following table summarizes the shorthand notation.
|
|
|
|
-------------------+-----------
|
|
Option | Expression~
|
|
-------------------+-----------
|
|
`filter` | `[gv]/.*/`
|
|
`left_margin` | `l[0-9]+`
|
|
`right_margin` | `r[0-9]+`
|
|
`stick_to_left` | `<` or `>`
|
|
`ignore_unmatched` | `iu[01]`
|
|
`ignore_groups` | `ig\[.*\]`
|
|
`align` | `a[lrc*]*`
|
|
`delimiter_align` | `d[lrc]`
|
|
`indentation` | `i[ksdn]`
|
|
-------------------+-----------
|
|
|
|
For your information, the same operation can be done in interactive mode as
|
|
follows:
|
|
|
|
- <Enter>
|
|
- `*`
|
|
- <Left>
|
|
- CTRL-X
|
|
- `[:;]\+`
|
|
|
|
{6} https://github.com/junegunn/vim-easy-align#alignment-options
|
|
|
|
|
|
< 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
|
|
`align` | string | `l` | 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> | `<` or `>` |
|
|
`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`
|
|
`align` | CTRL-A | `a[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 type in `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-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
|
|
}
|
|
<
|
|
If a pattern in `ignore_groups` is prepended by a `!`, it will have the
|
|
opposite meaning. For instance, if `ignore_groups` is given as `['!Comment']`,
|
|
delimiters that are not highlighted as Comment will be ignored during the
|
|
alignment.
|
|
|
|
|
|
< 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
|
|
<
|
|
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 "align' option. (The option can also be set in
|
|
interactive mode with the special key CTRL-A)
|
|
>
|
|
" Left alignment over the first two occurrences of delimiters
|
|
:EasyAlign = { 'align': 'll' }
|
|
|
|
" Right, left, center alignment over the 1st to 3rd occurrences of delimiters
|
|
:EasyAlign = { 'a': 'rlc' }
|
|
|
|
" Using shorthand notation
|
|
:EasyAlign = arlc
|
|
|
|
" Right, left, center alignment over the 2nd to 4th occurrences of delimiters
|
|
:EasyAlign 2=arlc
|
|
|
|
" (*) Repeating alignments (default: l, r, or c)
|
|
" Right, left, center, center, center, center, ...
|
|
:EasyAlign *=arlc
|
|
|
|
" (**) Alternating alignments (default: lr or rl)
|
|
" Right, left, center, right, left, center, ...
|
|
:EasyAlign **=arlc
|
|
|
|
" Right, left, center, center, center, ... repeating alignment
|
|
" over the 3rd to the last occurrences of delimiters
|
|
:EasyAlign 3=arlc*
|
|
|
|
" Right, left, center, right, left, center, ... alternating alignment
|
|
" over the 3rd to the last occurrences of delimiters
|
|
:EasyAlign 3=arlc**
|
|
<
|
|
|
|
< 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}{7}.
|
|
|
|
{7} https://github.com/junegunn/vim-easy-align/blob/2.9.6/autoload/easy_align.vim#L32-L46
|
|
|
|
|
|
Examples~
|
|
|
|
*easy-align-6-8-1*
|
|
>
|
|
let g:easy_align_delimiters = {
|
|
\ '>': { 'pattern': '>>\|=>\|>' },
|
|
\ '/': {
|
|
\ 'pattern': '//\+\|/\*\|\*/',
|
|
\ 'delimiter_align': 'l',
|
|
\ 'ignore_groups': ['!Comment'] },
|
|
\ ']': {
|
|
\ '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}{8} 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.
|
|
>
|
|
let g:easy_align_bypass_fold = 1
|
|
<
|
|
{8} https://github.com/junegunn/vim-easy-align/issues/14
|
|
|
|
|
|
< 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}{9} for more examples.
|
|
|
|
{9} https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md
|
|
|
|
|
|
*easy-align-9*
|
|
RELATED WORK *easy-align-related-work*
|
|
==============================================================================
|
|
|
|
- {DrChip's Alignment Tool for Vim}{10}
|
|
- {Tabular}{11}
|
|
|
|
{10} http://www.drchip.org/astronaut/vim/align.html
|
|
{11} https://github.com/godlygeek/tabular
|
|
|
|
|
|
*easy-align-10*
|
|
AUTHOR *easy-align-author*
|
|
==============================================================================
|
|
|
|
{Junegunn Choi}{12}
|
|
|
|
{12} https://github.com/junegunn
|
|
|
|
|
|
*easy-align-11*
|
|
LICENSE *easy-align-license*
|
|
==============================================================================
|
|
|
|
MIT
|
|
|
|
==============================================================================
|
|
vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap:
|