m-vim_plugins/vim-easy-align
1
0
Fork 0
mirror of https://github.com/junegunn/vim-easy-align.git synced 2025-11-11 11:23:49 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Junegunn Choi
2013-10-07 21:13:17 +09:00
parent 2bf1b2164d
commit 013fb54dd1
2 changed files with 100 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
README.md
View File

@@ -114,21 +114,21 @@ You can override these default rules or define your own rules with
#### Example command sequences #### Example command sequences
| With visual map | Description | Equivalent command | | With visual map | Description | Equivalent command |
| ------------------- | ------------------------------------------------------- | ------------------------------- | | ------------------- | ------------------------------------------------------- | ---------------------- |
| `<Enter><space>` | Alignment around 1st whitespaces | `:'<,'>EasyAlign\ ` | | `<Enter><space>` | Alignment around 1st whitespaces | `:'<,'>EasyAlign\ ` |
| `<Enter>2<space>` | Alignment around 2nd whitespaces | `:'<,'>EasyAlign2\ ` | | `<Enter>2<space>` | Alignment around 2nd whitespaces | `:'<,'>EasyAlign2\ ` |
| `<Enter>-<space>` | Alignment around the last whitespaces | `:'<,'>EasyAlign-\ ` | | `<Enter>-<space>` | Alignment around the last whitespaces | `:'<,'>EasyAlign-\ ` |
| `<Enter>-2<space>` | Alignment around the 2nd to last whitespaces | `:'<,'>EasyAlign-2\ ` | | `<Enter>-2<space>` | Alignment around the 2nd to last whitespaces | `:'<,'>EasyAlign-2\ ` |
| `<Enter>:` | Alignment around 1st colon (`key: value`) | `:'<,'>EasyAlign:` | | `<Enter>:` | Alignment around 1st colon (`key: value`) | `:'<,'>EasyAlign:` |
| `<Enter><Right>:` | Alignment around 1st colon (`key : value`) | `:'<,'>EasyAlign:{'s':0,'l':1}` | | `<Enter><Right>:` | Alignment around 1st colon (`key : value`) | `:'<,'>EasyAlign:s0l1` |
| `<Enter>=` | Alignment around 1st operators with = | `:'<,'>EasyAlign=` | | `<Enter>=` | Alignment around 1st operators with = | `:'<,'>EasyAlign=` |
| `<Enter>2=` | Alignment around 2nd operators with = | `:'<,'>EasyAlign2=` | | `<Enter>2=` | Alignment around 2nd operators with = | `:'<,'>EasyAlign2=` |
| `<Enter>3=` | Alignment around 3rd operators with = | `:'<,'>EasyAlign3=` | | `<Enter>3=` | Alignment around 3rd operators with = | `:'<,'>EasyAlign3=` |
| `<Enter>*=` | Alignment around all operators with = | `:'<,'>EasyAlign*=` | | `<Enter>*=` | Alignment around all operators with = | `:'<,'>EasyAlign*=` |
| `<Enter>**=` | Left-right alternating alignment around all = operators | `:'<,'>EasyAlign**=` | | `<Enter>**=` | Left-right alternating alignment around all = operators | `:'<,'>EasyAlign**=` |
| `<Enter><Enter>=` | Right alignment around 1st equals signs | `:'<,'>EasyAlign!=` | | `<Enter><Enter>=` | Right alignment around 1st equals signs | `:'<,'>EasyAlign!=` |
| `<Enter><Enter>**=` | Right-left alternating alignment around all = operators | `:'<,'>EasyAlign!**=` | | `<Enter><Enter>**=` | Right-left alternating alignment around all = operators | `:'<,'>EasyAlign!**=` |
#### Using regular expressions #### Using regular expressions
@@ -179,9 +179,9 @@ Go try out vim-easy-align right now, and come back later when you feel like it.
--- ---
### Non-interactive mode (command line) ### Using `EasyAlign` in command line
Instead of going into the interactive mode, you can type in arguments to Instead of going into the interactive mode, you can just type in arguments to
`:EasyAlign` command. `:EasyAlign` command.
```vim ```vim
@@ -223,8 +223,8 @@ You can even omit spaces between the arguments, so concisely (or cryptically):
- `:EasyAlign*/[:;]\+/{'s':1,'l':0}` - `:EasyAlign*/[:;]\+/{'s':1,'l':0}`
Nice. But let's make it even shorter. When you use write regular expression in Nice. But let's make it even shorter. Option values can be written in shorthand
command line, option values can be written in shorthand notation. notation.
- `:EasyAlign*/[:;]\+/s1l0` - `:EasyAlign*/[:;]\+/s1l0`
@@ -360,7 +360,7 @@ You can change the default rule by using one of these 4 methods.
2. Define global `g:easy_align_ignore_groups` list 2. Define global `g:easy_align_ignore_groups` list
3. Define a custom rule in `g:easy_align_delimiters` with `ignore_groups` option 3. Define a custom rule in `g:easy_align_delimiters` with `ignore_groups` option
4. Provide `ignore_groups` option to `:EasyAlign` command. 4. Provide `ignore_groups` option to `:EasyAlign` command.
e.g. `:EasyAlign:{'ig':[]}` e.g. `:EasyAlign:ig[]`
For example if you set `ignore_groups` option to be an empty list, you get For example if you set `ignore_groups` option to be an empty list, you get
@@ -379,10 +379,18 @@ Satisfied? :satisfied:
### Ignoring unmatched lines ### Ignoring unmatched lines
Lines without any matching delimiter are ignored as well (except in `ignore_unmatched` option determines how EasyAlign command processes lines that
right-align mode). do not have N-th delimiter.
For example, when aligning the following code block around the colons, 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,
```ruby ```ruby
{ {
@@ -406,13 +414,13 @@ this is usually what we want.
} }
``` ```
However, this default behavior is also configurable by using one of these 4 However, we can override this default behavior by setting `ignore_unmatched`
methods. option to zero using one of the following methods.
1. Press `CTRL-U` in interactive mode to toggle `ignore_unmatched` option 1. Press `CTRL-U` in interactive mode to toggle `ignore_unmatched` option
2. Set the global `g:easy_align_ignore_unmatched` variable to 0 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 3. Define a custom alignment rule with `ignore_unmatched` option set to 0
4. Provide `ignore_unmatched` option to `:EasyAlign` command. e.g. `:EasyAlign:{'iu':0}` 4. Provide `ignore_unmatched` option to `:EasyAlign` command. e.g. `:EasyAlign:iu0`
Then we get, Then we get,
@@ -446,7 +454,7 @@ banana += apple
cake ||= banana cake ||= banana
``` ```
However, with `:EasyAlign={'da':l}`, delimiters are left-aligned. However, with `:EasyAlign=dl`, delimiters are left-aligned.
```ruby ```ruby
apple = 1 apple = 1
@@ -454,7 +462,7 @@ banana += apple
cake ||= banana cake ||= banana
``` ```
And on `:EasyAlign={'da':c}`, center-aligned. And on `:EasyAlign=dc`, center-aligned.
```ruby ```ruby
apple = 1 apple = 1
@@ -486,7 +494,7 @@ then again we have `indentation` option. See the following example.
eggplant = 5 eggplant = 5
# Use the _s_hallowest indentation among the lines # Use the _s_hallowest indentation among the lines
# :EasyAlign={'idt':s} # :EasyAlign=is
apple = 1 apple = 1
banana = 2 banana = 2
cake = 3 cake = 3
@@ -494,7 +502,7 @@ then again we have `indentation` option. See the following example.
eggplant = 5 eggplant = 5
# Use the _d_eepest indentation among the lines # Use the _d_eepest indentation among the lines
# :EasyAlign={'idt':d} # :EasyAlign=id
apple = 1 apple = 1
banana = 2 banana = 2
cake = 3 cake = 3
@@ -502,7 +510,7 @@ then again we have `indentation` option. See the following example.
eggplant = 5 eggplant = 5
# Indentation: _n_one # Indentation: _n_one
# :EasyAlign={'idt':n} # :EasyAlign=in
apple = 1 apple = 1
banana = 2 banana = 2
cake = 3 cake = 3
@@ -514,26 +522,6 @@ Notice that `idt` is fuzzy-matched to `indentation`.
In interactive mode, you can change the option value with `CTRL-I` key. In interactive mode, you can change the option value with `CTRL-I` key.
### Left/right/center mode switch in interactive mode
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.
```vim
let g:easy_align_interactive_modes = ['l', 'r']
let g:easy_align_bang_interactive_modes = ['c', 'r']
```
### Alignments over multiple occurrences of delimiters ### Alignments over multiple occurrences of delimiters
As stated above, "N-th" parameter is used to target specific occurrences of As stated above, "N-th" parameter is used to target specific occurrences of
@@ -572,24 +560,27 @@ in interactive mode with the special key `CTRL-O`)
" Right, left, center alignment over the 1st to 3rd occurrences of delimiters " Right, left, center alignment over the 1st to 3rd occurrences of delimiters
:EasyAlign = { 'm': 'rlc' } :EasyAlign = { 'm': 'rlc' }
" Using shorthand notation
:EasyAlign = mrlc
" Right, left, center alignment over the 2nd to 4th occurrences of delimiters " Right, left, center alignment over the 2nd to 4th occurrences of delimiters
:EasyAlign 2={ 'm': 'rlc' } :EasyAlign 2=mrlc
" (*) Repeating alignments (default: l, r, or c) " (*) Repeating alignments (default: l, r, or c)
" Right, left, center, center, center, center, ... " Right, left, center, center, center, center, ...
:EasyAlign *={ 'm': 'rlc' } :EasyAlign *=mrlc
" (**) Alternating alignments (default: lr or rl) " (**) Alternating alignments (default: lr or rl)
" Right, left, center, right, left, center, ... " Right, left, center, right, left, center, ...
:EasyAlign **={ 'm': 'rlc' } :EasyAlign **=mrlc
" Right, left, center, center, center, ... repeating alignment " Right, left, center, center, center, ... repeating alignment
" over the 3rd to the last occurrences of delimiters " over the 3rd to the last occurrences of delimiters
:EasyAlign 3={ 'm': 'rlc*' } :EasyAlign 3=mrlc*
" Right, left, center, right, left, center, ... alternating alignment " Right, left, center, right, left, center, ... alternating alignment
" over the 3rd to the last occurrences of delimiters " over the 3rd to the last occurrences of delimiters
:EasyAlign 3={ 'm': 'rlc**' } :EasyAlign 3=mrlc**
``` ```
### Extending alignment rules ### Extending alignment rules

95
doc/easy_align.txt
View File

@@ -107,7 +107,29 @@ repeatable, non-interactive command recorded in `g:easy_align_last_command`.
:<C-R>=g:easy_align_last_command<Enter><Enter> :<C-R>=g:easy_align_last_command<Enter><Enter>
Non-interactive mode (command line) Left/right/center mode switch in interactive mode
-------------------------------------------------------------------------
*g:easy_align_interactive_modes*
*g:easy_align_bang_interactive_modes*
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.
let g:easy_align_interactive_modes = ['l', 'r']
let g:easy_align_bang_interactive_modes = ['c', 'r']
Using EasyAlign in command line
------------------------------------------------------------------------- -------------------------------------------------------------------------
Instead of going into the interactive mode, you can type in arguments to Instead of going into the interactive mode, you can type in arguments to
@@ -150,8 +172,8 @@ You can even omit spaces between the arguments, so concisely (or cryptically):
:EasyAlign*/[:;]\+/{'s':1,'l':''} :EasyAlign*/[:;]\+/{'s':1,'l':''}
Nice. But let's make it even shorter. When you use write regular expression in Nice. But let's make it even shorter. Option values can be written in shorthand
command line, option values can be written in shorthand notation. notation.
:EasyAlign*/[:;]\+/s1l0 :EasyAlign*/[:;]\+/s1l0
@@ -265,7 +287,7 @@ You can change the default rule by using one of these 4 methods.
2. Define global `g:easy_align_ignore_groups` list 2. Define global `g:easy_align_ignore_groups` list
3. Define a custom rule in `g:easy_align_delimiters` with 'ignore_groups' option 3. Define a custom rule in `g:easy_align_delimiters` with 'ignore_groups' option
4. Provide 'ignore_groups' option to `:EasyAlign` command. 4. Provide 'ignore_groups' option to `:EasyAlign` command.
e.g. :EasyAlign:{'is':[]} e.g. :EasyAlign:ig[]
For example if you set 'ignore_groups' option to be an empty list, you get For example if you set 'ignore_groups' option to be an empty list, you get
@@ -282,10 +304,18 @@ For example if you set 'ignore_groups' option to be an empty list, you get
Ignoring unmatched lines *g:easy_align_ignore_unmatched* Ignoring unmatched lines *g:easy_align_ignore_unmatched*
------------------------------------------------------------------------- -------------------------------------------------------------------------
Lines without any matching delimiter are ignored as well (except in 'ignore_unmatched' option determines how EasyAlign command processes lines that
right-align mode). do not have N-th delimiter.
For example, when aligning the following code block around the colons, 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 { apple: proc {
@@ -305,14 +335,14 @@ this is usually what we want.
grapefruits: 3 grapefruits: 3
} }
However, this default behavior is also configurable by using one of these 4 However, we can override this default behavior by setting 'ignore_unmatched'
methods. option to zero using one of the following methods.
1. Press CTRL-U in interactive mode to toggle 'ignore_unmatched' option 1. Press CTRL-U in interactive mode to toggle 'ignore_unmatched' option
2. Set the global `g:easy_align_ignore_unmatched` variable to 0 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 3. Define a custom alignment rule with 'ignore_unmatched' option set to 0
4. Provide 'ignore_unmatched' option to `:EasyAlign` command. 4. Provide 'ignore_unmatched' option to `:EasyAlign` command.
e.g. :EasyAlign:{'iu':0} e.g. :EasyAlign:iu0
Then we get, Then we get,
@@ -342,13 +372,13 @@ By default, delimiters are right-aligned as follows.
banana += apple banana += apple
cake ||= banana cake ||= banana
However, with ':EasyAlign={'da':l}', delimiters are left-aligned. However, with ':EasyAlign=dl', delimiters are left-aligned.
apple = 1 apple = 1
banana += apple banana += apple
cake ||= banana cake ||= banana
And on ':EasyAlign={'da':c}', center-aligned. And on ':EasyAlign=dc', center-aligned.
apple = 1 apple = 1
banana += apple banana += apple
@@ -379,7 +409,7 @@ But then again we have 'indentation' option. See the following example.
eggplant = 5 eggplant = 5
# Use the _s_hallowest indentation among the lines # Use the _s_hallowest indentation among the lines
# :EasyAlign={'idt':s} # :EasyAlign=is
apple = 1 apple = 1
banana = 2 banana = 2
cake = 3 cake = 3
@@ -387,7 +417,7 @@ But then again we have 'indentation' option. See the following example.
eggplant = 5 eggplant = 5
# Use the _d_eepest indentation among the lines # Use the _d_eepest indentation among the lines
# :EasyAlign={'idt':d} # :EasyAlign=id
apple = 1 apple = 1
banana = 2 banana = 2
cake = 3 cake = 3
@@ -395,7 +425,7 @@ But then again we have 'indentation' option. See the following example.
eggplant = 5 eggplant = 5
# Indentation: _n_one # Indentation: _n_one
# :EasyAlign={'idt':n} # :EasyAlign=in
apple = 1 apple = 1
banana = 2 banana = 2
cake = 3 cake = 3
@@ -408,28 +438,6 @@ Notice that 'idt' is fuzzy-matched to 'indentation'.
In interactive mode, you can change the option value with `CTRL-I` key. In interactive mode, you can change the option value with `CTRL-I` key.
Left/right/center mode switch in interactive mode
-------------------------------------------------------------------------
*g:easy_align_interactive_modes*
*g:easy_align_bang_interactive_modes*
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.
let g:easy_align_interactive_modes = ['l', 'r']
let g:easy_align_bang_interactive_modes = ['c', 'r']
Alignments over multiple occurrences of delimiters Alignments over multiple occurrences of delimiters
------------------------------------------------------------------------- -------------------------------------------------------------------------
@@ -466,24 +474,27 @@ in interactive mode with the special key CTRL-O)
" Right, left, center alignment over the 1st to 3rd occurrences of delimiters " Right, left, center alignment over the 1st to 3rd occurrences of delimiters
:EasyAlign = { 'm': 'rlc' } :EasyAlign = { 'm': 'rlc' }
" Using shorthand notation
:EasyAlign = mrlc
" Right, left, center alignment over the 2nd to 4th occurrences of delimiters " Right, left, center alignment over the 2nd to 4th occurrences of delimiters
:EasyAlign 2={ 'm': 'rlc' } :EasyAlign 2=mrlc
" (*) Repeating alignments (default: l, r, or c) " (*) Repeating alignments (default: l, r, or c)
" Right, left, center, center, center, center, ... " Right, left, center, center, center, center, ...
:EasyAlign *={ 'm': 'rlc' } :EasyAlign *=mrlc
" (**) Alternating alignments (default: lr or rl) " (**) Alternating alignments (default: lr or rl)
" Right, left, center, right, left, center, ... " Right, left, center, right, left, center, ...
:EasyAlign **={ 'm': 'rlc' } :EasyAlign **=mrlc
" Right, left, center, center, center, ... repeating alignment " Right, left, center, center, center, ... repeating alignment
" over the 3rd to the last occurrences of delimiters " over the 3rd to the last occurrences of delimiters
:EasyAlign 3={ 'm': 'rlc*' } :EasyAlign 3=mrlc*
" Right, left, center, right, left, center, ... alternating alignment " Right, left, center, right, left, center, ... alternating alignment
" over the 3rd to the last occurrences of delimiters " over the 3rd to the last occurrences of delimiters
:EasyAlign 3={ 'm': 'rlc**' } :EasyAlign 3=mrlc**
Extending alignment rules *g:easy_align_delimiters* Extending alignment rules *g:easy_align_delimiters*