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

<CTRL-P> to switch to live interactive mode (#44)

Browse Source
This commit is contained in:
Junegunn Choi
2014-11-30 00:30:00 +09:00
parent 2595ebf933
commit f6586bad39
4 changed files with 315 additions and 438 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
README.md
View File

@@ -22,27 +22,16 @@ Features
- Optimized for code editing - Optimized for code editing
- Takes advantage of syntax highlighting feature to avoid unwanted alignments - Takes advantage of syntax highlighting feature to avoid unwanted alignments
### _"I already have a similar one. Should I switch?"_
Maybe or maybe not. See [related work](https://github.com/junegunn/vim-easy-align#related-work) section.
Installation Installation
------------ ------------
Either [download zip file](http://www.vim.org/scripts/script.php?script_id=4520) User your favorite plugin manager.
and extract in ~/.vim or
[use](https://github.com/tpope/vim-pathogen)
[your](https://github.com/gmarik/vundle)
[favorite](https://github.com/junegunn/vim-plug)
[plugin](https://github.com/Shougo/neobundle.vim)
[manager](https://github.com/MarcWeber/vim-addon-manager).
- [Vundle](https://github.com/gmarik/vundle) Using [vim-plug](https://github.com/junegunn/vim-plug):
1. Add `Plugin 'junegunn/vim-easy-align'` to .vimrc
2. Run `:PluginInstall` ```vim
- [vim-plug](https://github.com/junegunn/vim-plug) Plug 'junegunn/vim-easy-align'
1. Add `Plug 'junegunn/vim-easy-align'` to .vimrc ```
2. Run `:PlugInstall`
TL;DR - One-minute guide TL;DR - One-minute guide
------------------------ ------------------------
@@ -53,8 +42,8 @@ Add the following mappings to your .vimrc.
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>) " Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
vmap <Enter> <Plug>(EasyAlign) vmap <Enter> <Plug>(EasyAlign)
" Start interactive EasyAlign for a motion/text object (e.g. <Leader>aip) " Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap <Leader>a <Plug>(EasyAlign) nmap ga <Plug>(EasyAlign)
``` ```
And with the following lines of text, And with the following lines of text,
@@ -71,8 +60,8 @@ try these commands:
- `v`isual-select `i`nner `p`aragraph - `v`isual-select `i`nner `p`aragraph
- Start EasyAlign command (`<Enter>`) - Start EasyAlign command (`<Enter>`)
- Align around `=` - Align around `=`
- `<Leader>aip=` - `gaip=`
- Start EasyAlign command (`<Leader>a`) for `i`nner `p`aragraph - Start EasyAlign command (`ga`) for `i`nner `p`aragraph
- Align around `=` - Align around `=`
Notice that the commands are repeatable with `.` key if you have installed Notice that the commands are repeatable with `.` key if you have installed
@@ -131,13 +120,13 @@ your .vimrc as below:
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>) " Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
vmap <Enter> <Plug>(EasyAlign) vmap <Enter> <Plug>(EasyAlign)
" Start interactive EasyAlign for a motion/text object (e.g. <Leader>aip) " Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap <Leader>a <Plug>(EasyAlign) nmap ga <Plug>(EasyAlign)
``` ```
With these mappings, you can align text with only a few keystrokes. With these mappings, you can align text with only a few keystrokes.
1. `<Enter>` key in visual mode, or `<Leader>a` followed by a motion or a text 1. `<Enter>` key in visual mode, or `ga` followed by a motion or a text
object to start interactive mode object to start interactive mode
1. Optional: Enter keys to select alignment mode (left, right, or center) 1. Optional: Enter keys to select alignment mode (left, right, or center)
1. Optional: N-th delimiter (default: 1) 1. Optional: N-th delimiter (default: 1)
@@ -222,8 +211,9 @@ If you're performing a complex alignment where multiple options should be
carefully adjusted, try "live interactive mode" where you can preview the result carefully adjusted, try "live interactive mode" where you can preview the result
of the alignment on-the-fly as you type in. of the alignment on-the-fly as you type in.
Live interactive mode can be started with either `<Plug>(LiveEasyAlign)` or Live interactive mode can be started with either `<Plug>(LiveEasyAlign)` map
`:LiveEasyAlign` command. 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 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 regular expression) again to finalize the alignment. This allows you to preview
@@ -739,86 +729,12 @@ Advanced examples and use cases
See [EXAMPLES.md](https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md) See [EXAMPLES.md](https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md)
for more examples. for more examples.
Related work Related work
------------ ------------
There are two well-known plugins with the same goal as that of easy-align. - [DrChip's Alignment Tool for Vim](http://www.drchip.org/astronaut/vim/align.html)
- [DrChip's Alignment Tool for Vim](http://www.drchip.org/astronaut/vim/align.html) (herein will be referred to as "Align")
- [Tabular](https://github.com/godlygeek/tabular) - [Tabular](https://github.com/godlygeek/tabular)
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 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 easy-align.
### Ease of use
As the name implies, 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 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 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 easy-align under default configuration and a mapping, it can
be done with just two keystrokes: `<Enter>:`
```javascript
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
Virtually every aspect of easy-align is being tested with a comprehensive
set of test cases using [Vader.vim](https://github.com/junegunn/vader.vim).
### "Okay. So should I switch?"
Maybe, but I can't really say. I have no ambition to make easy-align
an absolute superior to the others. For some cases, 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!
Author Author
------ ------

28
autoload/easy_align.vim
View File

@@ -146,7 +146,7 @@ endfunction
function! s:echon(l, n, r, d, o, warn) function! s:echon(l, n, r, d, o, warn)
let tokens = [ let tokens = [
\ ['Function', ':EasyAlign'], \ ['Function', s:live ? ':LiveEasyAlign' : ':EasyAlign'],
\ ['ModeMsg', get(s:mode_labels, a:l, a:l)], \ ['ModeMsg', get(s:mode_labels, a:l, a:l)],
\ ['None', ' ']] \ ['None', ' ']]
@@ -617,7 +617,7 @@ function! s:shift_opts(opts, key, vals)
endif endif
endfunction endfunction
function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis) function! s:interactive(range, modes, n, d, opts, rules, vis, bvis)
let mode = s:shift(a:modes, 1) let mode = s:shift(a:modes, 1)
let n = a:n let n = a:n
let d = a:d let d = a:d
@@ -636,7 +636,7 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis)
let undo = 0 let undo = 0
let rdrw = 1 let rdrw = 1
endif endif
if a:live && !empty(d) if s:live && !empty(d)
let output = s:process(a:range, mode, n, d, s:normalize_options(opts), regx, a:rules, a:bvis) let output = s:process(a:range, mode, n, d, s:normalize_options(opts), regx, a:rules, a:bvis)
let &undolevels = &undolevels " Break undo block let &undolevels = &undolevels " Break undo block
call s:update_lines(output.todo) call s:update_lines(output.todo)
@@ -713,6 +713,13 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis)
call s:shift_opts(opts, 'iu', vals['ignore_unmatched']) call s:shift_opts(opts, 'iu', vals['ignore_unmatched'])
elseif ch == "\<C-G>" elseif ch == "\<C-G>"
call s:shift_opts(opts, 'ig', vals['ignore_groups']) call s:shift_opts(opts, 'ig', vals['ignore_groups'])
elseif ch == "\<C-P>"
if !empty(d) && s:live
let ch = d
break
else
let s:live = 1
endif
elseif c == "\<Left>" elseif c == "\<Left>"
let opts['stl'] = 1 let opts['stl'] = 1
let opts['lm'] = 0 let opts['lm'] = 0
@@ -737,7 +744,7 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis)
silent! call remove(opts, 'a') silent! call remove(opts, 'a')
endif endif
elseif ch == "\<C-_>" || ch == "\<C-X>" elseif ch == "\<C-_>" || ch == "\<C-X>"
if a:live && regx && !empty(d) if s:live && regx && !empty(d)
break break
endif endif
@@ -746,7 +753,7 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis)
if !empty(ch) && s:valid_regexp(ch) if !empty(ch) && s:valid_regexp(ch)
let regx = 1 let regx = 1
let d = ch let d = ch
if !a:live | break | endif if !s:live | break | endif
else else
let warn = 'Invalid regular expression: '.ch let warn = 'Invalid regular expression: '.ch
endif endif
@@ -770,7 +777,7 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis)
if empty(d) if empty(d)
if has_key(a:rules, ch) if has_key(a:rules, ch)
let d = ch let d = ch
if !a:live if !s:live
break break
endif endif
else else
@@ -789,7 +796,7 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, bvis)
endif endif
endif endif
endwhile endwhile
if a:live if s:live
let copts = call('s:summarize', output.summarize) let copts = call('s:summarize', output.summarize)
let g:easy_align_last_command = s:echon('', n, regx, d, copts, '') let g:easy_align_last_command = s:echon('', n, regx, d, copts, '')
end end
@@ -1073,6 +1080,7 @@ function! s:align(bang, live, visualmode, first_line, last_line, expr)
let range = [a:first_line, a:last_line] let range = [a:first_line, a:last_line]
let modes = s:interactive_modes(a:bang) let modes = s:interactive_modes(a:bang)
let mode = modes[0] let mode = modes[0]
let s:live = a:live
let rules = s:easy_align_delimiters_default let rules = s:easy_align_delimiters_default
if exists('g:easy_align_delimiters') if exists('g:easy_align_delimiters')
@@ -1086,11 +1094,11 @@ function! s:align(bang, live, visualmode, first_line, last_line, expr)
try try
if bypass_fold | let &l:foldmethod = 'manual' | endif if bypass_fold | let &l:foldmethod = 'manual' | endif
if empty(n) && empty(ch) || a:live if empty(n) && empty(ch) || s:live
let [mode, n, ch, opts, regexp] = s:interactive(range, copy(modes), n, ch, opts, rules, vis, a:live, bvis) let [mode, n, ch, opts, regexp] = s:interactive(range, copy(modes), n, ch, opts, rules, vis, bvis)
endif endif
if !a:live if !s:live
let output = s:process(range, mode, n, ch, s:normalize_options(opts), regexp, rules, bvis) let output = s:process(range, mode, n, ch, s:normalize_options(opts), regexp, rules, bvis)
call s:update_lines(output.todo) call s:update_lines(output.todo)
let copts = call('s:summarize', output.summarize) let copts = call('s:summarize', output.summarize)

571
doc/easy_align.txt
View File

@@ -1,51 +1,43 @@
easy-align.txt vim-easy-align Last change: August 14 2014 easy-align.txt easy-align Last change: November 30 2014
EASY-ALIGN - TABLE OF CONTENTS *easyalign* *easy-align* *easy-align-toc*
VIM-EASY-ALIGN - TABLE OF CONTENTS *easyalign* *easy-align* *easy-align-toc*
============================================================================== ==============================================================================
Demo |easy-align-1| vim-easy-align
Features |easy-align-2| Demo |easy-align-1|
"I already have a similar one. Should I switch?" |easy-align-2-1| Features |easy-align-2|
Installation |easy-align-3| Installation |easy-align-3|
TLDR - One-minute guide |easy-align-4| TLDR - One-minute guide |easy-align-4|
Usage |easy-align-5| Usage |easy-align-5|
Concept of alignment rule |easy-align-5-1| Concept of alignment rule |easy-align-5-1|
Execution models |easy-align-5-2| Execution models |easy-align-5-2|
1. Using <Plug> mappings |easy-align-5-2-1| 1. Using <Plug> mappings |easy-align-5-2-1|
2. Using :EasyAlign command |easy-align-5-2-2| 2. Using :EasyAlign command |easy-align-5-2-2|
Interactive mode |easy-align-5-3| Interactive mode |easy-align-5-3|
Predefined alignment rules |easy-align-5-3-1| Predefined alignment rules |easy-align-5-3-1|
Examples |easy-align-5-3-2| Examples |easy-align-5-3-2|
Using regular expressions |easy-align-5-3-3| Using regular expressions |easy-align-5-3-3|
Alignment options in interactive mode |easy-align-5-3-4| Alignment options in interactive mode |easy-align-5-3-4|
Live interactive mode |easy-align-5-4| Live interactive mode |easy-align-5-4|
Non-interactive mode |easy-align-5-5| Non-interactive mode |easy-align-5-5|
Partial alignment in blockwise-visual mode |easy-align-5-6| Partial alignment in blockwise-visual mode |easy-align-5-6|
Alignment options |easy-align-6| Alignment options |easy-align-6|
List of options |easy-align-6-1| List of options |easy-align-6-1|
Filtering lines |easy-align-6-2| Filtering lines |easy-align-6-2|
Examples |easy-align-6-2-1| Examples |easy-align-6-2-1|
Ignoring delimiters in comments or strings |easy-align-6-3| Ignoring delimiters in comments or strings |easy-align-6-3|
Ignoring unmatched lines |easy-align-6-4| Ignoring unmatched lines |easy-align-6-4|
Aligning delimiters of different lengths |easy-align-6-5| Aligning delimiters of different lengths |easy-align-6-5|
Adjusting indentation |easy-align-6-6| Adjusting indentation |easy-align-6-6|
Alignments over multiple occurrences of delimiters |easy-align-6-7| Alignments over multiple occurrences of delimiters |easy-align-6-7|
Extending alignment rules |easy-align-6-8| Extending alignment rules |easy-align-6-8|
Examples |easy-align-6-8-1| Examples |easy-align-6-8-1|
Other options |easy-align-7| Other options |easy-align-7|
Disabling &foldmethod during alignment |easy-align-7-1| Disabling &foldmethod during alignment |easy-align-7-1|
Left/right/center mode switch in interactive mode |easy-align-7-2| Left/right/center mode switch in interactive mode |easy-align-7-2|
Advanced examples and use cases |easy-align-8| Advanced examples and use cases |easy-align-8|
Related work |easy-align-9| Related work |easy-align-9|
Ease of use |easy-align-9-1| Author |easy-align-10|
Clean |easy-align-9-2| License |easy-align-11|
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* VIM-EASY-ALIGN *vim-easy-align*
@@ -70,42 +62,27 @@ FEATURES *easy-align-features*
============================================================================== ==============================================================================
- Easy to use - Easy to use
- Comes with a predefined set of alignment rules - Comes with a predefined set of alignment rules
- Provides a fast and intuitive interface - Provides a fast and intuitive interface
- Extensible - Extensible
- You can define your own rules - You can define your own rules
- Supports arbitrary regular expressions - Supports arbitrary regular expressions
- Optimized for code editing - Optimized for code editing
- Takes advantage of syntax highlighting feature to avoid unwanted alignments - 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* *easy-align-3*
INSTALLATION *easy-align-installation* INSTALLATION *easy-align-installation*
============================================================================== ==============================================================================
Either {download zip file}{2} and extract in ~/.vim or {use}{3} {your}{4} User your favorite plugin manager.
{favorite}{5} {plugin}{6} {manager}{7}.
{2} http://www.vim.org/scripts/script.php?script_id=4520 Using {vim-plug}{2}:
{3} https://github.com/tpope/vim-pathogen >
{4} https://github.com/gmarik/vundle Plug 'junegunn/vim-easy-align'
{5} https://github.com/junegunn/vim-plug <
{6} https://github.com/Shougo/neobundle.vim {2} https://github.com/junegunn/vim-plug
{7} https://github.com/MarcWeber/vim-addon-manager
- {Vundle}{4}
- Add `Plugin 'junegunn/vim-easy-align'` to .vimrc
- Run `:PluginInstall`
- {vim-plug}{5}
- Add `Plug 'junegunn/vim-easy-align'` to .vimrc
- Run `:PlugInstall`
*easy-align-4* *easy-align-4*
@@ -113,12 +90,14 @@ TLDR - ONE-MINUTE GUIDE *easy-align-tldr-one-minute-guide*
============================================================================== ==============================================================================
Add the following mappings to your .vimrc. Add the following mappings to your .vimrc.
*<Plug>(EasyAlign)*
> >
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>) " Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
vmap <Enter> <Plug>(EasyAlign) vmap <Enter> <Plug>(EasyAlign)
" Start interactive EasyAlign for a motion/text object (e.g. <Leader>aip) " Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap <Leader>a <Plug>(EasyAlign) nmap ga <Plug>(EasyAlign)
< <
And with the following lines of text, And with the following lines of text,
> >
@@ -129,19 +108,19 @@ And with the following lines of text,
try these commands: try these commands:
- vip<Enter>= - vip<Enter>=
- `v`isual-select `i`nner `p`aragraph - `v`isual-select `i`nner `p`aragraph
- Start EasyAlign command (<Enter>) - Start EasyAlign command (<Enter>)
- Align around `=` - Align around `=`
- <Leader>aip= - `gaip=`
- Start EasyAlign command (<Leader>a) for `i`nner `p`aragraph - Start EasyAlign command (`ga`) for `i`nner `p`aragraph
- Align around `=` - Align around `=`
Notice that the commands are repeatable with `.` key if you have installed 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 {repeat.vim}{3}. Install {visualrepeat}{4} as well if you want to repeat in
visual mode. visual mode.
{8} https://github.com/tpope/vim-repeat {3} https://github.com/tpope/vim-repeat
{9} https://github.com/vim-scripts/visualrepeat {4} https://github.com/vim-scripts/visualrepeat
*easy-align-5* *easy-align-5*
@@ -157,7 +136,7 @@ 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". 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, 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> , which is identified by a single character, DELIMITER KEY, such as <Space>,
`=`, `:`, `.`, `|`, `&`, `#`, and `,`. `=`, `:`, `.`, `|`, `&`, `#`, and `,`.
Think of it as a shortcut. Instead of writing regular expression and setting Think of it as a shortcut. Instead of writing regular expression and setting
@@ -171,20 +150,20 @@ several options, you can just type in a single character.
There are two ways to use easy-align. There are two ways to use easy-align.
1. Using <Plug> mappings~ 1. Using <Plug> mappings~
*easy-align-1-using-plug-mappings* *easy-align-1-using-plug-mappings*
*easy-align-5-2-1* *easy-align-5-2-1*
The recommended method is to use <Plug> mappings as described earlier. The recommended method is to use <Plug> mappings as described earlier.
*<Plug>(EasyAlign)* *<Plug>(LiveEasyAlign)* ----------------------+--------+-----------------------------------------------------
Mapping | Mode | Description ~
Mapping | Mode | Description~ ----------------------+--------+-----------------------------------------------------
----------------------- | ------ | ---------------------------------------------------- <Plug>(EasyAlign) | normal | Start interactive mode for a motion/text object
<Plug>(EasyAlign) | normal | Start interactive mode for a motion/text object <Plug>(EasyAlign) | visual | Start interactive mode for the selection
<Plug>(EasyAlign) | visual | Start interactive mode for the selection <Plug>(LiveEasyAlign) | normal | Start live-interactive mode for a motion/text object
<Plug>(LiveEasyAlign) | normal | Start live-interactive mode for a motion/text object <Plug>(LiveEasyAlign) | visual | Start live-interactive mode for the selection
<Plug>(LiveEasyAlign) | visual | Start live-interactive mode for the selection ----------------------+--------+-----------------------------------------------------
2. Using :EasyAlign command~ 2. Using :EasyAlign command~
@@ -196,12 +175,14 @@ The recommended method is to use <Plug> mappings as described earlier.
If you prefer command-line or do not want to start interactive mode, you can If you prefer command-line or do not want to start interactive mode, you can
use `:EasyAlign` command instead. use `:EasyAlign` command instead.
Mode | Command~ -------------------------------------------+-----------------------------------------------
------------------------------------------ | ------------------------------------------------ Mode | Command ~
Interactive mode | `:EasyAlign[!] [OPTIONS]` -------------------------------------------+-----------------------------------------------
Live interactive mode | `:LiveEasyAlign[!] [...]` Interactive mode | `:EasyAlign[!] [OPTIONS]`
Non-interactive mode (predefined rules) | `:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]` Live interactive mode | `:LiveEasyAlign[!] [...]`
Non-interactive mode (regular expressions) | `:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]` Non-interactive mode (predefined rules) | `:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]`
Non-interactive mode (regular expressions) | `:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]`
-------------------------------------------+-----------------------------------------------
< Interactive mode >__________________________________________________________~ < Interactive mode >__________________________________________________________~
@@ -214,66 +195,71 @@ your .vimrc as below:
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>) " Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
vmap <Enter> <Plug>(EasyAlign) vmap <Enter> <Plug>(EasyAlign)
" Start interactive EasyAlign for a motion/text object (e.g. <Leader>aip) " Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap <Leader>a <Plug>(EasyAlign) nmap ga <Plug>(EasyAlign)
< <
With these mappings, you can align text with only a few keystrokes. With these mappings, you can align text with only a few keystrokes.
1. <Enter> key in visual mode, or <Leader>a followed by a motion or a text object 1. <Enter> key in visual mode, or `ga` followed by a motion or a text object to
to start interactive mode start interactive mode
2. Optional: Enter keys to select alignment mode (left, right, or center) 2. Optional: Enter keys to select alignment mode (left, right, or center)
3. Optional: N-th delimiter (default: 1) 3. Optional: N-th delimiter (default: 1)
- `1` Around the 1st occurrences of delimiters - `1` Around the 1st occurrences of delimiters
- `2` Around the 2nd occurrences of delimiters - `2` Around the 2nd occurrences of delimiters
- ... - ...
- `*` Around all occurrences of delimiters - `*` Around all occurrences of delimiters
- `**` Left-right alternating alignment around all delimiters - `**` Left-right alternating alignment around all delimiters
- `-` Around the last occurrences of delimiters (`-1`) - `-` Around the last occurrences of delimiters (`-1`)
- `-2` Around the second to last occurrences of delimiters - `-2` Around the second to last occurrences of delimiters
- ... - ...
4. Delimiter key (a single keystroke; <Space> , `=`, `:`, `.`, `|`, `&`, `#`, `,`) 4. Delimiter key (a single keystroke; <Space>, `=`, `:`, `.`, `|`, `&`, `#`, `,`)
Predefined alignment rules~ Predefined alignment rules~
*easy-align-predefined-alignment-rules* *easy-align-predefined-alignment-rules*
*easy-align-5-3-1* *easy-align-5-3-1*
Delimiter key | Description/Use cases~ --------------+--------------------------------------------------------------------
------------- | -------------------------------------------------------------------- Delimiter key | Description/Use cases ~
--------------+--------------------------------------------------------------------
<Space> | General alignment around whitespaces <Space> | General alignment around whitespaces
`=` | Operators containing equals sign (`=` , `==,` `!=` , `+=` , `&&=` , ...) `=` | Operators containing equals sign ( `=` , `==,` `!=` , `+=` , `&&=` , ...)
`:` | Suitable for formatting JSON or YAML `:` | Suitable for formatting JSON or YAML
`.` | Multi-line method chaining `.` | Multi-line method chaining
`,` | Multi-line method arguments `,` | Multi-line method arguments
`&` | LaTeX tables (matches `&` and `\\` ) `&` | LaTeX tables (matches `&` and `\\` )
`#` | Ruby/Python comments `#` | Ruby/Python comments
<Bar> | Table markdown <Bar> | Table markdown
--------------+--------------------------------------------------------------------
*g:easy_align_delimiters* *g:easy_align_delimiters*
You can override these default rules or define your own rules with You can override these default rules or define your own rules with
`g:easy_align_delimiters`, which will be described in the later section `g:easy_align_delimiters`, which will be described in {the later section}{5}.
(|easy-align-extending-alignment-rules|).
{5} https://github.com/junegunn/vim-easy-align#extending-alignment-rules
Examples~ Examples~
*easy-align-examples* *easy-align-examples*
*easy-align-5-3-2* *easy-align-5-3-2*
With visual map | Description | Equivalent command~ ------------------+------------------------------------+--------------------
------------------- | ---------------------------------- | --------------------- With visual map | Description | Equivalent command ~
<Enter><Space> | Around 1st whitespaces | :'<,'>EasyAlign\ ------------------+------------------------------------+--------------------
<Enter>2<Space> | Around 2nd whitespaces | :'<,'>EasyAlign2\ <Enter><Space> | Around 1st whitespaces | :'<,'>EasyAlign\
<Enter>-<Space> | Around the last whitespaces | :'<,'>EasyAlign-\ <Enter>2<Space> | Around 2nd whitespaces | :'<,'>EasyAlign2\
<Enter>-2<Space> | Around the 2nd to last whitespaces | :'<,'>EasyAlign-2\ <Enter>-<Space> | Around the last whitespaces | :'<,'>EasyAlign-\
<Enter>: | Around 1st colon (`key: value`) | :'<,'>EasyAlign: <Enter>-2<Space> | Around the 2nd to last whitespaces | :'<,'>EasyAlign-2\
<Enter><Right>: | Around 1st colon (`key : value`) | :'<,'>EasyAlign:<l1 <Enter>: | Around 1st colon ( `key: value` ) | :'<,'>EasyAlign:
<Enter>= | Around 1st operators with = | :'<,'>EasyAlign= <Enter><Right>: | Around 1st colon ( `key : value` ) | :'<,'>EasyAlign:<l1
<Enter>3= | Around 3rd operators with = | :'<,'>EasyAlign3= <Enter>= | Around 1st operators with = | :'<,'>EasyAlign=
<Enter>*= | Around all operators with = | :'<,'>EasyAlign*= <Enter>3= | Around 3rd operators with = | :'<,'>EasyAlign3=
<Enter>**= | Left-right alternating around = | :'<,'>EasyAlign**= <Enter>*= | Around all operators with = | :'<,'>EasyAlign*=
<Enter><Enter>= | Right alignment around 1st = | :'<,'>EasyAlign!= <Enter>**= | Left-right alternating around = | :'<,'>EasyAlign**=
<Enter><Enter>**= | Right-left alternating around = | :'<,'>EasyAlign!**= <Enter><Enter>= | Right alignment around 1st = | :'<,'>EasyAlign!=
<Enter><Enter>**= | Right-left alternating around = | :'<,'>EasyAlign!**=
------------------+------------------------------------+--------------------
Using regular expressions~ Using regular expressions~
@@ -281,36 +267,40 @@ Using regular expressions~
*easy-align-5-3-3* *easy-align-5-3-3*
Instead of finishing the command with a predefined delimiter key, you can type 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 in a regular expression after CTRL-/ or CTRL-X key. For example, if you want
align text around all occurrences of numbers: to align text around all occurrences of numbers:
- <Enter> - <Enter>
- `*` - `*`
- CTRL-X - CTRL-X
- `[0-9]\+` - `[0-9]\+`
Alignment options in interactive mode~ Alignment options in interactive mode~
*easy-align-alignment-options-in-interactive-mode* *easy-align-alignment-options-in-interactive-mode*
*easy-align-5-3-4* *easy-align-5-3-4*
While in interactive mode, you can set alignment options using special shortcut While in interactive mode, you can set alignment options using special
keys listed below. The meaning of each option will be described in the shortcut keys listed below. The meaning of each option will be described in
following sections (|easy-align-alignment-options|). {the following sections}{6}.
Key | Option | Values~ --------+--------------------+---------------------------------------------------
--------- | ------------------ | -------------------------------------------------- Key | Option | Values ~
CTRL-F | `filter` | Input string (`[gv]/.*/?` ) --------+--------------------+---------------------------------------------------
CTRL-I | `indentation` | shallow, deep, none, keep CTRL-F | `filter` | Input string ( `[gv]/.*/?` )
CTRL-L | `left_margin` | Input number or string CTRL-I | `indentation` | shallow, deep, none, keep
CTRL-R | `right_margin` | Input number or string CTRL-L | `left_margin` | Input number or string
CTRL-D | `delimiter_align` | left, center, right CTRL-R | `right_margin` | Input number or string
CTRL-U | `ignore_unmatched` | 0, 1 CTRL-D | `delimiter_align` | left, center, right
CTRL-G | `ignore_groups` | [], ['String'], ['Comment'], ['String', 'Comment'] CTRL-U | `ignore_unmatched` | 0, 1
CTRL-A | `align` | Input string (`/[lrc]+\*{0,2}/` ) CTRL-G | `ignore_groups` | [], ["String'], ["Comment'], ["String', "Comment']
<Left> | `stick_to_left` | `{ 'stick_to_left': 1, 'left_margin': 0 }` CTRL-A | `align` | Input string ( `/[lrc]+\*{0,2}/` )
<Right> | `stick_to_left` | `{ 'stick_to_left': 0, 'left_margin': 1 }` <Left> | `stick_to_left` | `{ 'stick_to_left': 1, 'left_margin': 0 }`
<Down> | `*_margin` | `{ 'left_margin': 0, 'right_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 >_____________________________________________________~ < Live interactive mode >_____________________________________________________~
@@ -321,15 +311,16 @@ If you're performing a complex alignment where multiple options should be
carefully adjusted, try "live interactive mode" where you can preview the carefully adjusted, try "live interactive mode" where you can preview the
result of the alignment on-the-fly as you type in. result of the alignment on-the-fly as you type in.
*:LiveEasyAlign* *<Plug>(LiveEasyAlign)* *:LiveEasyAlign*
Live interactive mode can be started with either <Plug>(LiveEasyAlign) or Live interactive mode can be started with either <Plug>(LiveEasyAlign) map or
`:LiveEasyAlign` command. `: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 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 regular expression) again to finalize the alignment. This allows you to
the result of the alignment and freely change the delimiter using backspace key preview the result of the alignment and freely change the delimiter using
without leaving the interactive mode. backspace key without leaving the interactive mode.
< Non-interactive mode >______________________________________________________~ < Non-interactive mode >______________________________________________________~
@@ -353,14 +344,14 @@ Instead of starting interactive mode, you can use declarative, non-interactive
:EasyAlign */[:;]\+/ :EasyAlign */[:;]\+/
:EasyAlign **/[:;]\+/ :EasyAlign **/[:;]\+/
< <
A command can end with alignment options, each of which will be discussed in A command can end with alignment options, {each of which will be discussed in
detail later (|easy-align-alignment-options|), in Vim dictionary format. detail later}{6}, in Vim dictionary format.
- `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }` - `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }`
`stick_to_left` of 1 means that the matched delimiter should be positioned `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 right next to the preceding token, and `left_margin` of 0 removes the margin
the left. So we get: on the left. So we get:
> >
apple;: banana:: cake apple;: banana:: cake
data;; exchange:; format data;; exchange:; format
@@ -373,24 +364,26 @@ 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. Option values can be written in shorthand Nice. But let's make it even shorter. Option values can be written in
notation. shorthand notation.
- `:EasyAlign*/[:;]\+/<l0` - `:EasyAlign*/[:;]\+/<l0`
The following table summarizes the shorthand notation. The following table summarizes the shorthand notation.
-------------------+-----------
Option | Expression~ Option | Expression~
------------------ | -------------- -------------------+-----------
`filter` | `[gv]/.*/` `filter` | `[gv]/.*/`
`left_margin` | `l[0-9]+` `left_margin` | `l[0-9]+`
`right_margin` | `r[0-9]+` `right_margin` | `r[0-9]+`
`stick_to_left` | `<` or `>` `stick_to_left` | `<` or `>`
`ignore_unmatched` | `iu[01]` `ignore_unmatched` | `iu[01]`
`ignore_groups` | `ig\[.*\]` `ignore_groups` | `ig\[.*\]`
`align` | `a[lrc*]*` `align` | `a[lrc*]*`
`delimiter_align` | `d[lrc]` `delimiter_align` | `d[lrc]`
`indentation` | `i[ksdn]` `indentation` | `i[ksdn]`
-------------------+-----------
For your information, the same operation can be done in interactive mode as For your information, the same operation can be done in interactive mode as
follows: follows:
@@ -399,7 +392,9 @@ follows:
- `*` - `*`
- <Left> - <Left>
- CTRL-X - CTRL-X
- `[:;]\+` - `[:;]\+`
{6} https://github.com/junegunn/vim-easy-align#alignment-options
< Partial alignment in blockwise-visual mode >________________________________~ < Partial alignment in blockwise-visual mode >________________________________~
@@ -409,7 +404,8 @@ follows:
In blockwise-visual mode (CTRL-V), EasyAlign command aligns only the selected In blockwise-visual mode (CTRL-V), EasyAlign command aligns only the selected
text in the block, instead of the whole lines in the range. text in the block, instead of the whole lines in the range.
Consider the following case where you want to align text around `=>` operators. Consider the following case where you want to align text around `=>`
operators.
> >
my_hash = { :a => 1, my_hash = { :a => 1,
:aa => 2, :aa => 2,
@@ -417,8 +413,8 @@ Consider the following case where you want to align text around `=>` operators.
< <
In non-blockwise visual mode (`v` / `V`), <Enter>= won't work since the 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 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, blockwise-visual mode (CTRL-V), and select the text around`=>` operators, then
then press <Enter>= . press <Enter>=.
> >
my_hash = { :a => 1, my_hash = { :a => 1,
:aa => 2, :aa => 2,
@@ -437,19 +433,21 @@ ALIGNMENT OPTIONS *easy-align-alignment-options*
*easy-align-list-of-options* *easy-align-list-of-options*
*easy-align-6-1* *easy-align-6-1*
Option | Type | Default | Description~ -------------------+---------+-----------------------+--------------------------------------------------------
------------------ | ------- | --------------------- | ------------------------------------------------------- Option | Type | Default | Description ~
`filter` | string | | Line filtering expression: `g/../` or `v/../` -------------------+---------+-----------------------+--------------------------------------------------------
`left_margin` | number | 1 | Number of spaces to attach before delimiter `filter` | string | | Line filtering expression: `g/../` or `v/../`
`left_margin` | string | `' '` | String to attach before delimiter `left_margin` | number | 1 | Number of spaces to attach before delimiter
`right_margin` | number | 1 | Number of spaces to attach after delimiter `left_margin` | string | `' '` | String to attach before delimiter
`right_margin` | string | `' '` | String to attach after delimiter `right_margin` | number | 1 | Number of spaces to attach after delimiter
`stick_to_left` | boolean | 0 | Whether to position delimiter on the left-side `right_margin` | string | `' '` | String to attach after delimiter
`ignore_groups` | list | ['String', 'Comment'] | Delimiters in these syntax highlight groups are ignored `stick_to_left` | boolean | 0 | Whether to position delimiter on the left-side
`ignore_unmatched` | boolean | 1 | Whether to ignore lines without matching delimiter `ignore_groups` | list | ["String', "Comment'] | Delimiters in these syntax highlight groups are ignored
`indentation` | string | `k` | Indentation method (keep, deep, shallow, none) `ignore_unmatched` | boolean | 1 | Whether to ignore lines without matching delimiter
`delimiter_align` | string | `r` | Determines how to align delimiters of different lengths `indentation` | string | `k` | Indentation method (keep, deep, shallow, none)
`align` | string | `l` | Alignment modes for multiple occurrences of delimiters `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): There are 4 ways to set alignment options (from lowest precedence to highest):
@@ -458,20 +456,19 @@ There are 4 ways to set alignment options (from lowest precedence to highest):
3. Option values can be given as arguments to `:EasyAlign` command 3. Option values can be given as arguments to `:EasyAlign` command
4. Option values can be set in interactive mode using special shortcut keys 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 ~
-------------------+-----------------+-------------+--------------------------------
Option name | Shortcut key | Abbreviated | Global variable~ `filter` | CTRL-F | `[gv]/.*/` |
------------------ | ------------------- | -------------- | ------------------------------- `left_margin` | CTRL-L | `l[0-9]+` |
`filter` | CTRL-F | `[gv]/.*/` | `right_margin` | CTRL-R | `r[0-9]+` |
`left_margin` | CTRL-L | `l[0-9]+` | `stick_to_left` | <Left>, <Right> | `<` or `>` |
`right_margin` | CTRL-R | `r[0-9]+` | `ignore_groups` | CTRL-G | `ig\[.*\]` | `g:easy_align_ignore_groups`
`stick_to_left` | <Left> , <Right> | `<` or `>` | `ignore_unmatched` | CTRL-U | `iu[01]` | `g:easy_align_ignore_unmatched`
`ignore_groups` | CTRL-G | `ig\[.*\]` | `g:easy_align_ignore_groups` `indentation` | CTRL-I | `i[ksdn]` | `g:easy_align_indentation`
`ignore_unmatched` | CTRL-U | `iu[01]` | `g:easy_align_ignore_unmatched` `delimiter_align` | CTRL-D | `d[lrc]` | `g:easy_align_delimiter_align`
`indentation` | CTRL-I | `i[ksdn]` | `g:easy_align_indentation` `align` | CTRL-A | `a[lrc*]*` |
`delimiter_align` | CTRL-D | `d[lrc]` | `g:easy_align_delimiter_align` -------------------+-----------------+-------------+--------------------------------
`align` | CTRL-A | `a[lrc*]*` |
< Filtering lines >___________________________________________________________~ < Filtering lines >___________________________________________________________~
@@ -482,14 +479,15 @@ 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. 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/` 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/'}` 2. In command-line, it can be written in dictionary format: `{'filter':
'g/pat/'}`
3. Or in shorthand notation: `g/pat/` or `v/pat/` 3. Or in shorthand notation: `g/pat/` or `v/pat/`
(You don't need to escape '/'s in the regular expression) (You don't need to escape "/'s in the regular expression)
Examples~ Examples~
*easy-align-examples-2* *easy-align-examples*
*easy-align-6-2-1* *easy-align-6-2-1*
> >
" Start interactive mode with filter option set to g/hello/ " Start interactive mode with filter option set to g/hello/
@@ -509,6 +507,8 @@ Examples~
EasyAlign can be configured to ignore delimiters in certain syntax highlight EasyAlign can be configured to ignore delimiters in certain syntax highlight
groups, such as code comments or strings. By default, delimiters that are groups, such as code comments or strings. By default, delimiters that are
highlighted as code comments or strings are ignored. highlighted as code comments or strings are ignored.
*g:easy_align_ignore_groups*
> >
" Default: " Default:
" If a delimiter is in a highlight group whose name matches " If a delimiter is in a highlight group whose name matches
@@ -567,8 +567,8 @@ alignment.
*easy-align-ignoring-unmatched-lines* *easy-align-ignoring-unmatched-lines*
*easy-align-6-4* *easy-align-6-4*
`ignore_unmatched` option determines how EasyAlign command processes lines that `ignore_unmatched` option determines how EasyAlign command processes lines
do not have N-th delimiter. that do not have N-th delimiter.
1. In left-alignment mode, they are ignored 1. In left-alignment mode, they are ignored
2. In right or center-alignment mode, they are not ignored, and the last tokens 2. In right or center-alignment mode, they are not ignored, and the last tokens
@@ -602,6 +602,8 @@ However, we can override this default behavior by setting `ignore_unmatched`
option to zero using one of the following 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
*g:easy_align_ignore_unmatched*
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. 4. Provide `ignore_unmatched` option to `:EasyAlign` command. e.g.
@@ -622,9 +624,11 @@ Then we get,
*easy-align-aligning-delimiters-of-different-lengths* *easy-align-aligning-delimiters-of-different-lengths*
*easy-align-6-5* *easy-align-6-5*
*g:easy_align_delimiter_align*
Global `g:easy_align_delimiter_align` option and rule-wise/command-wise Global `g:easy_align_delimiter_align` option and rule-wise/command-wise
`delimiter_align` option determines how matched delimiters of different lengths `delimiter_align` option determines how matched delimiters of different
are aligned. lengths are aligned.
> >
apple = 1 apple = 1
banana += apple banana += apple
@@ -704,8 +708,8 @@ In interactive mode, you can change the option value with CTRL-I key.
*easy-align-alignments-over-multiple-occurrences-of-delimiters* *easy-align-alignments-over-multiple-occurrences-of-delimiters*
*easy-align-6-7* *easy-align-6-7*
As stated above, "N-th" parameter is used to target specific occurrences of the As stated above, "N-th" parameter is used to target specific occurrences of
delimiter when it appears multiple times in each line. the delimiter when it appears multiple times in each line.
To recap: To recap:
> >
@@ -727,9 +731,9 @@ To recap:
" Right-left ALTERNATING alignment around all occurrences of delimiters " Right-left ALTERNATING alignment around all occurrences of delimiters
:EasyAlign! **= :EasyAlign! **=
< <
In addition to these, you can fine-tune alignments over multiple occurrences of In addition to these, you can fine-tune alignments over multiple occurrences
the delimiters with 'align' option. (The option can also be set in interactive of the delimiters with "align' option. (The option can also be set in
mode with the special key CTRL-A) interactive mode with the special key CTRL-A)
> >
" Left alignment over the first two occurrences of delimiters " Left alignment over the first two occurrences of delimiters
:EasyAlign = { 'align': 'll' } :EasyAlign = { 'align': 'll' }
@@ -767,13 +771,13 @@ mode with the special key CTRL-A)
Although the default rules should cover the most of the use cases, you can 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`. 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}. You may refer to the definitions of the default alignment rules {here}{7}.
{10} https://github.com/junegunn/vim-easy-align/blob/2.9.6/autoload/easy_align.vim#L32-L46 {7} https://github.com/junegunn/vim-easy-align/blob/2.9.6/autoload/easy_align.vim#L32-L46
Examples~ Examples~
*easy-align-examples-3* *easy-align-examples*
*easy-align-6-8-1* *easy-align-6-8-1*
> >
let g:easy_align_delimiters = { let g:easy_align_delimiters = {
@@ -813,16 +817,16 @@ OTHER OPTIONS *easy-align-other-options*
*g:easy_align_bypass_fold* *g:easy_align_bypass_fold*
{It is reported}{11} that 'foldmethod' value of `expr` or `syntax` can {It is reported}{8} that 'foldmethod' value of `expr` or `syntax` can
significantly slow down the alignment when editing a large, complex file with significantly slow down the alignment when editing a large, complex file with
many folds. To alleviate this issue, EasyAlign provides an option to many folds. To alleviate this issue, EasyAlign provides an option to
temporarily set 'foldmethod' to `manual` during the alignment task. In order to temporarily set 'foldmethod' to `manual` during the alignment task. In order
enable this feature, set `g:easy_align_bypass_fold` switch to 1. 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 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 >_________________________~ < Left/right/center mode switch in interactive mode >_________________________~
*easy-align-left-right-center-mode-switch-in-interactive-mode* *easy-align-left-right-center-mode-switch-in-interactive-mode*
@@ -834,15 +838,14 @@ and changes to right and center mode as you press enter keys, while the bang
version first starts in right-alignment mode. version first starts in right-alignment mode.
- `:EasyAlign` - `:EasyAlign`
- Left, Right, Center - Left, Right, Center
- `:EasyAlign!` - `:EasyAlign!`
- Right, Left, Center - Right, Left, Center
If you do not prefer this default mode transition, you can define your own If you do not prefer this default mode transition, you can define your own
settings as follows. settings as follows.
*g:easy_align_interactive_modes* *g:easy_align_interactive_modes* *g:easy_align_bang_interactive_modes*
*g:easy_align_bang_interactive_modes*
> >
let g:easy_align_interactive_modes = ['l', 'r'] let g:easy_align_interactive_modes = ['l', 'r']
let g:easy_align_bang_interactive_modes = ['c', 'r'] let g:easy_align_bang_interactive_modes = ['c', 'r']
@@ -852,115 +855,29 @@ settings as follows.
ADVANCED EXAMPLES AND USE CASES *easy-align-advanced-examples-and-use-cases* ADVANCED EXAMPLES AND USE CASES *easy-align-advanced-examples-and-use-cases*
============================================================================== ==============================================================================
See {EXAMPLES.md}{12} for more examples. See {EXAMPLES.md}{9} for more examples.
{12} https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md {9} https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md
*easy-align-9* *easy-align-9*
RELATED WORK *easy-align-related-work* RELATED WORK *easy-align-related-work*
============================================================================== ==============================================================================
There are two well-known plugins with the same goal as that of easy-align. - {DrChip's Alignment Tool for Vim}{10}
- {Tabular}{11}
- {DrChip's Alignment Tool for Vim}{13} (herein will be referred to as "Align") {10} http://www.drchip.org/astronaut/vim/align.html
- {Tabular}{14} {11} https://github.com/godlygeek/tabular
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 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 easy-align.
< Ease of use >_______________________________________________________________~
*easy-align-ease-of-use*
*easy-align-9-1*
As the name implies, 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*
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*
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 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 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 easy-align an
absolute superior to the others. For some cases, 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* *easy-align-10*
AUTHOR *easy-align-author* AUTHOR *easy-align-author*
============================================================================== ==============================================================================
{Junegunn Choi}{16} {Junegunn Choi}{12}
{16} https://github.com/junegunn {12} https://github.com/junegunn
*easy-align-11* *easy-align-11*

36
test/interactive.vader
View File

@@ -485,6 +485,42 @@ Expect:
|)batch_size(|) Fixnum(|)nil (|)number of maximum items to be assigned at once(| |)batch_size(|) Fixnum(|)nil (|)number of maximum items to be assigned at once(|
|)logger (|) Logger(|)nil (|) logger instance for debug logs(| |)logger (|) Logger(|)nil (|) logger instance for debug logs(|
Do (Switching to live interactive mode):
vip\<Enter>
* Switch to live interactive mode
\<C-P>
|
\<C-L><\<Enter>
\<C-R>>\<Enter>
***
**
\<BS>\<BS>\<BS>
**|\<Enter>|
Expect:
|>Option <|> Type<|>Default<|> Description<|
|>-- <|> --<|>-- <|> --<|
|>threads <|> Fixnum<|>1 <|> number of threads in the thread pool<|
|>queues <|> Fixnum<|>1 <|> number of concurrent queues<|
|>queue_size<|> Fixnum<|>1000 <|> size of each queue<|
|>interval <|>Numeric<|>0 <|> dispatcher interval for batch processing<|
|>batch <|>Boolean<|>false <|> enables batch processing mode<|
|>batch_size<|> Fixnum<|>nil <|>number of maximum items to be assigned at once<|
|>logger <|> Logger<|>nil <|> logger instance for debug logs<|
Do (Toggling live interactive mode):
vip\<Enter>
* Enable live mode
\<C-P>
|*
* Disable live mode
\<C-P>
gg2jdG
Expect:
| Option | Type | Default | Description |
| -- | -- | -- | -- |
Do (live interactive mode!): Do (live interactive mode!):
vip\<Space>r\<Enter> vip\<Space>r\<Enter>
| |