junegunn / vim-easy-align

:sunflower: A Vim alignment plugin

vim-easy-align

A simple, easy-to-use Vim alignment plugin.

Installation

Use your favorite plugin manager.

Using vim-plug:

Plug 'junegunn/vim-easy-align'

Quick start guide

Add the following mappings to your .vimrc.

" Start interactive EasyAlign in visual mode (e.g. vipga)
xmap ga <Plug>(EasyAlign)

" Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap ga <Plug>(EasyAlign)

Then with the following lines of text,

apple   =red
grass+=green
sky-=   blue

try these commands:

• vipga=
  • visual-select inner paragraph
  • Start EasyAlign command (ga)
  • Align around =
• gaip=
  • Start EasyAlign command (ga) for inner paragraph
  • Align around =

Demo

Click on each image to see from the beginning.

Using predefined alignment rules

An alignment rule is a predefined set of options for common alignment tasks, which is identified by a single character, such as <Space>, =, :, ., |, &, #, and ,.

=

• = Around the 1st occurrences
• 2= Around the 2nd occurrences
• *= Around all occurrences
• **= Left/Right alternating alignment around all occurrences
• <Enter> Switching between left/right/center alignment modes

<Space>

• <Space> Around the 1st occurrences of whitespaces
• 2<Space> Around the 2nd occurrences
• -<Space> Around the last occurrences
• <Enter><Enter>2<Space> Center-alignment around the 2nd occurrences

,

• The predefined comma-rule places a comma right next to the preceding token without margin ({'stick_to_left': 1, 'left_margin': 0})
• You can change it with <Right> arrow

Using regular expression

You can use an arbitrary regular expression by

• pressing <Ctrl-X> in interactive mode
• or using :EasyAlign /REGEX/ command in visual mode or in normal mode with a range (e.g. :%)

Different ways to start

This demo shows how you can start interactive mode with visual selection or use non-interactive :EasyAlign command.

Aligning table cells

Check out various alignment options and "live interactive mode".

Syntax-aware alignment

Delimiters in strings and comments are ignored by default.

Using blockwise-visual mode

You can limit the scope with blockwise-visual mode.

Usage

Flow of execution

There are two ways to use easy-align.

1. <Plug> mappings (interactive mode)

The recommended method is to use <Plug>(EasyAlign) mapping in normal and visual mode. They are usually mapped to ga, but you can choose any key sequences.

nmap ga <Plug>(EasyAlign)
xmap ga <Plug>(EasyAlign)

1. ga key in visual mode, or ga followed by a motion or a text object to start interactive mode
2. (Optional) Enter keys to cycle between 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>, =, :, ., |, &, #, ,) or an arbitrary regular expression followed by <CTRL-X>

2. Using :EasyAlign command

If you prefer command-line, use :EasyAlign command instead.

" Using predefined rules
:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]

" Using regular expression
:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]

Regular expression vs. predefined rules

You can use regular expressions but it's usually much easier to use predefined alignment rules that you can trigger with a single keystroke.

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

You can also define your own rules with g:easy_align_delimiters which will be described in the later section.

---

Interactive mode

Interactive mode is started either with <Plug>(EasyAlign) mapping or with :EasyAlign command with no argument.

Examples using predefined rules

Keystrokes	Description	Equivalent command
<Space>	Around 1st whitespaces	:'<,'>EasyAlign\
2<Space>	Around 2nd whitespaces	:'<,'>EasyAlign2\
-<Space>	Around the last whitespaces	:'<,'>EasyAlign-\
-2<Space>	Around the 2nd to last whitespaces	:'<,'>EasyAlign-2\
:	Around 1st colon (key: value)	:'<,'>EasyAlign:
<Right>:	Around 1st colon (key : value)	:'<,'>EasyAlign:>l1
=	Around 1st operators with =	:'<,'>EasyAlign=
3=	Around 3rd operators with =	:'<,'>EasyAlign3=
*=	Around all operators with =	:'<,'>EasyAlign*=
**=	Left-right alternating around =	:'<,'>EasyAlign**=
<Enter>=	Right alignment around 1st =	:'<,'>EasyAlign!=
<Enter>**=	Right-left alternating around =	:'<,'>EasyAlign!**=

Instead of finishing the alignment with a delimiter key, you can type in a regular expression if you press <CTRL-/> or <CTRL-X>.

Alignment options in interactive mode

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.

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 }

Live interactive mode

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.

:EasyAlign command

Instead of starting interactive mode, you can use 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, 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

You don't have to write complete names as long as they're distinguishable.

• :EasyAlign * /[:;]\+/ { 'stl': 1, 'l': 0 }

You can even omit spaces between the arguments.

• :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]

Partial alignment in blockwise-visual mode

In blockwise-visual mode (CTRL-V), EasyAlign command aligns only the selected text in the block, instead of the whole lines in the range.

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>-=

Alignment options

List of options

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

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

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

" 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

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 following regular expressions, 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.

To make ignore_groups work, and to debug the related issues, it is useful to know which highlight group a certain location in a file belongs to. A special function exists for this purpose, returning exactly the name of the highlight group that is used by the easy align plugin.

" Highlight group name of the cursor position
echo easy_align#get_highlight_group_name()

" Highlight group name of the line 10, column 20
echo easy_align#get_highlight_group_name(10, 20)

Ignoring unmatched lines

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

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

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

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

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.

Examples

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
\   }
\ }

Other options

Disabling &foldmethod during alignment

It is reported 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

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.

let g:easy_align_interactive_modes = ['l', 'r']
let g:easy_align_bang_interactive_modes = ['c', 'r']

Advanced examples and use cases

See EXAMPLES.md for more examples.

Related work

• DrChip's Alignment Tool for Vim
• Tabular

Author

Junegunn Choi

License

MIT

vim-easy-align's Issues

Does not ignore delimiter at the end of a comment

# vim: set filetype=yaml:

---
cdh_version: 4.2.1

The demo animation is too fast!

<CTRL-/> not working in GVim

Can't align around quotes(both double and single)

I want to align some comments inside my .vimrc:

autocmd BufNewFile,BufRead *.sql set filetype=mysql " force mysql highlight
autocmd FocusLost          * silent! :wa                    " addition to autowriteall

When I select them, press Enter, then Ctrl-X for a regular expression and then Enter again. Command line shows :EasyAlign /"/ and comments are not aligned. Neither it works with \%x22(char code for ") as regex.

Key to toggle `stick_to_left` option in interactive mode

Align N-th delimiter as custom delimiter

Is there a way to align using the N-th parameter such as:

-) or 2=

Inside of the easy_align_delimiters variable? What I'm looking to do is:

let g:easy_align_delimiters = 
{
    'pattern' : ')',
    'left_margin' : 1,
    'right_margin' : 0,
    'stick_to_left' : 0,
    'n-th_param' : '-'
}

Or something similar...

mode_sequence expansion

lr* -> lrrr...
lr** -> lrlrlr...

Repeat of visual <Plug>(LiveEasyAlign) broken

Since f6586ba, repeating an alignment in visual mode using <Plug>(EasyAlignRepeat) doesn't work if the first alignment was done in live visual mode. It appears to do the alignment and then immediately undo it. For example:

vmap <CR> <Plug>(LiveEasyAlign)
vmap <C-^> <Plug>(EasyAlignRepeat)

operating on this text:

1    let VCSCommandCVSExec = ''
2    let VCSCommandCVSDiffOpt = '--internal-diff'
3    let VCSCommandBZRExec = ''
4
5    let VCSCommandSVKExec = ''
6    let VCSCommandDisableMappings = 1

If I select lines 1-3 and press <CR>== it aligns the =s, but then if I select 5-6 after that and press <C-^> the problem described above happens.

I tried to fix it but could only cause more problems to show up in the Vader tests.

Aligning around "

I have this snippet of code:

call s:Color('CtrlPNoEntries', 'base7', 'orange') " there are no entries
call s:Color('CtrlPMatch', 'green') " the matching part
call s:Color('CtrlPLinePre', 'base2') " the '>' in the match window
call s:Color('CtrlPPrtBase', 'magenta') " wat
call s:Color('CtrlPPrtText', 'cyan') " the text in the prompt

I'm trying to align it in order to become this:

call s:Color('CtrlPNoEntries', 'base7', 'orange') " there are no entries
call s:Color('CtrlPMatch', 'green')               " the matching part
call s:Color('CtrlPLinePre', 'base2')             " the '>' in the match window
call s:Color('CtrlPPrtBase', 'magenta')           " the wft
call s:Color('CtrlPPrtText', 'cyan')              " the text in the prompt

I tried using <C-x> in interactive mode and insert " as a regex, but it doesn't seem to work. I also tried this:

let g:easy_align_delimiters = { '"': { 'pattern': '"' } }

but neither did this.

The only way I managed to make it work is by using " as the regular expression (note the two spaces), which however leaves me with extra spaces surrounding the double quotes, like this:

call s:Color('CtrlPNoEntries', 'base7', 'orange')  "  there are no entries

Am I doing something wrong? Thanks in advance, and great plugin btw!

"Unknown delimiter:" when pressing <Enter> again to toggle right-justification

"Unknown delimiter:" when pressing again to toggle right-justification
What's the matter? How to use right justification?

Suggestion: Do nothing when 'nomodifiable' is set

I have mapped CR to EasyAlign in visual mode, but sometimes I get sloppy with my fingers and accidentally select and hit enter. Sometimes I do this in plugin buffers (like gitv) that are not normal editing buffers (and have enter mapped to command). This start EasyAlign, but that doesn't make sense in that buffer.

Since EasyAlign cannot complete the operation in a 'nomodifiable' buffer, maybe it should do nothing (immediately exit)?

(My workaround solution is to unmap EasyAlign in that buffer, so this is not a big deal for me.)

Spurious undo in live interactive mode

If a delimiter exists but is in an ignored group, undo will be triggered when no changes have been made, and it undos another level for every attempted change in the command. For example:

printf("foo = %f\n", foo);
printf("foobar = %f\n", foobar);

Using <Plug>LiveEasyAlign to align the =s makes no change because the =s are in strings, but undo is triggered anyway. Easy enough to fix that I don't want to fork the repository:

diff --git a/autoload/easy_align.vim b/autoload/easy_align.vim
index dbaa73f..e0730f2 100644
--- a/autoload/easy_align.vim
+++ b/autoload/easy_align.vim
@@ -640,7 +640,9 @@ function! s:interactive(range, modes, n, d, opts, rules, vis, live, 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
       call s:update_lines(output.todo)
-      let undo = 1
+      if !empty(output.todo)
+        let undo = 1
+      endif
       let rdrw = 1
     endif
     if rdrw

Regular expression in interactive mode

Proper implementation of visual-repeat

1. Repeating visual-repeat

When repeating a Visual mode operator, the operator will be applied to the
same amount of text as the last time:

• Linewise Visual mode: The same number of lines.
• Blockwise Visual mode: The same number of lines and columns.
• Normal Visual mode within one line: The same number of characters.
• Normal Visual mode with several lines: The same number of lines, in the
  last line the same number of characters as in the last line the last time.
  The start of the text is the Cursor position. If the "$" command was used as
  one of the last commands to extend the highlighted text, the repeating will
  be applied up to the rightmost column of the longest line.

Alignment of vim comments

let g:EasyGrepReplaceWindowMode=2   " autowriteall all changes during a search and replace session
let g:EasyGrepOptionPrefix='<leader>e' " shortcut to turn on and off certain grepoptions
let g:EasyGrepRecursive=1        " turn on recurse option for replacement
let g:EasyGrepCommand=1                " using system 'grepprg' instead of 'vimgrep

Better would be:

let g:EasyGrepReplaceWindowMode=2      " autowriteall all changes during a search and replace session
let g:EasyGrepOptionPrefix='<leader>e' " shortcut to turn on and off certain grepoptions
let g:EasyGrepRecursive=1              " turn on recurse option for replacement
let g:EasyGrepCommand=1                " using system 'grepprg' instead of 'vimgrep

My solution doesn't work:

let g:easy_align_delimiters = {
\ '"': { 'pattern': ' \(\S\+\s*[;=]\)\@=',  'left_margin': 1, 'right_margin': 1, 'stick_to_left': 0 } }

Are there any resources where I can look up those things?

Feature request: Improve speed

Hi,

I have not looked at the code for vim-easy-align, so I am not sure to which extent it is optimized or not. However, when I use the :EasyAlign command for relatively complex tables that spans multiple lines and columns, I find it is rather slow. If there is any chance of optimizing the code for more speed, that would be great!

Add option to add specific keys

Thanks for the work on this great plugin, much appreciated!I have a question, for example:

This is (example)
Yet another (example)

When I visual select that block, and align on the key ), it is an unknown delimiter key for EasyAlign.
In the very well written EasyAlign documentation, I see this are the only known delimiter keys:

Delimiter key (a single keystroke; <Space> , `=`, `:`, `.`, `|`, `&`, `,`)

So I want to be able to add custom delimiter keys like '(' or '[' or ", or even in future cases, characters like 'e' or 'o'.

Any thoughts on this?

Aligning on <-

In the R language, it is common practice to use the combination <- for assignment. It would be nice if there were a way to align on this.

Example:

x  <- 5
something.longer<-       83

becomes

x                <- 5
something.longer <- 83

Could you suggest an easy way to achieve this using vim-easy-align?

Fewer keystrokes to align on =

I often need to align around the = sign within a paragraph. I created a function to do this operation and mapped it to a leader key.

Perhaps this is useful for others

https://gist.github.com/nisaacson/4e17cb6abc4345833416

Feature request: Add pattern for LaTeX

Hi,

I like your plugin! I've been using Tabular, and happened to stumble upon this plugin by chance, and I think I will make the switch!

My request is to add & as a predefined delimiter. I know that I can use regexp with <CTRL-X> and that I may define custom patterns myself, but I still feel like the & for LaTeX tables and environments is important enough that it should be included by default.

Adding allign to comments

I was wondering if the plugin could be extended by adding alignment to comments. Like in the following python code:

var1 = 10 # This is a variable
var2 = 1000 # This is another variable

Which would produce:

var1 = 10   # This is a variable
var2 = 1000 # This is another variable

Also, for comment using /**/. Like

/*
* This is a comentary
*/

Which would became

/*
 * This is a comentary
 */

plugin not working anymore with latest vim

I've compiled vim from sources with all the patches, and when I try to use easy-align all that happens is that the cursor move to the first line / first column of the file. the text I selected is not aligned at all.

It looks like the problem appeared with one of the latest patches (e.g. patch 530 seems to have modified something about ranges), but I'm not sure which one or how I can discover it. If you need some help just ask, I'll do some more tests.

here's my vim version:

VIM - Vi IMproved 7.4 (2013 Aug 10, compiled Nov 28 2014 09:00:28)
MacOS X (unix) version
Included patches: 1-537
Compiled by Homebrew
Huge version without GUI.  Features included (+) or not (-):
+acl             +farsi           +mouse_netterm   +syntax
+arabic          +file_in_path    +mouse_sgr       +tag_binary
+autocmd         +find_in_path    -mouse_sysmouse  +tag_old_static
-balloon_eval    +float           +mouse_urxvt     -tag_any_white
-browse          +folding         +mouse_xterm     -tcl
++builtin_terms  -footer          +multi_byte      +terminfo
+byte_offset     +fork()          +multi_lang      +termresponse
+cindent         -gettext         -mzscheme        +textobjects
-clientserver    -hangul_input    +netbeans_intg   +title
+clipboard       +iconv           +path_extra      -toolbar
+cmdline_compl   +insert_expand   +perl            +user_commands
+cmdline_hist    +jumplist        +persistent_undo +vertsplit
+cmdline_info    +keymap          +postscript      +virtualedit
+comments        +langmap         +printer         +visual
+conceal         +libcall         +profile         +visualextra
+cryptv          +linebreak       +python          +viminfo
+cscope          +lispindent      -python3         +vreplace
+cursorbind      +listcmds        +quickfix        +wildignore
+cursorshape     +localmap        +reltime         +wildmenu
+dialog_con      -lua             +rightleft       +windows
+diff            +menu            +ruby            +writebackup
+digraphs        +mksession       +scrollbind      -X11
-dnd             +modify_fname    +signs           -xfontset
-ebcdic          +mouse           +smartindent     -xim
+emacs_tags      -mouseshape      -sniff           -xsmp
+eval            +mouse_dec       +startuptime     -xterm_clipboard
+ex_extra        -mouse_gpm       +statusline      -xterm_save
+extra_search    -mouse_jsbterm   -sun_workshop    -xpm
   system vimrc file: "$VIM/vimrc"
     user vimrc file: "$HOME/.vimrc"
 2nd user vimrc file: "~/.vim/vimrc"
      user exrc file: "$HOME/.exrc"
  fall-back for $VIM: "/usr/local/share/vim"
Compilation: /usr/bin/clang -c -I. -Iproto -DHAVE_CONFIG_H   -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk -DMACOS_X_UNIX  -Os -w -pipe -march=native -mmacosx-version-min=10.10 -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=1
Linking: /usr/bin/clang   -L. -L/usr/local/lib -L/usr/local/lib -Wl,-headerpad_max_install_names -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk -o vim        -lm  -lncurses -liconv -framework Cocoa   -fstack-protector  -L/System/Library/Perl/5.18/darwin-thread-multi-2level/CORE -lperl -framework Python   -lruby.2.0.0 -lobjc

Error when using delimiter alignment option

If I'm calling EasyAlign with a delimiter alignment option, like :EasyAlign {'a':'l'}, I'm getting the following error:

:EasyAlign (_) {'a': 'l'}
Error detected while processing function easy_align#align..<SNR>172_align..<SNR>172_interactive:
line   55:
E716: Key not present in Dictionary: m, 1)
E116: Invalid arguments for function strpart(opts.m, 1)
E15: Invalid expression: mode . strpart(opts.m, 1)

New feature: Ignore expression

It would be very nice to be able to add an ignore expression during aligning. For instance, given the following code:

print *, 'Plotting isentrope data:', trim(fname) // 't_p.dat'
call plot(ta,        'T', pa/1.0e5, 'p', trim(fname) // 't_p.dat')
print *, 'Plotting isentrope data:', trim(fname) // 'p_u.dat'
call plot(pa/1.0e5,  'p', ua,       'u', trim(fname) // 'p_u.dat')
print *, 'Plotting isentrope data:', trim(fname) // 'p_c.dat'
call plot(pa/1.0e5,  'p', ca,       'c', trim(fname) // 'p_c.dat')
print *, 'Plotting isentrope data:', trim(fname) // 'a_p.dat'
call plot(aa,        'A', pa/1.0e5, 'p', trim(fname) // 'a_p.dat')
print *, 'Plotting isentrope data:', trim(fname) // 'a_u.dat'
call plot(aa,        'A', ua,       'p', trim(fname) // 'a_u.dat')
print *, 'Plotting isentrope data:', trim(fname) // 'a_c.dat'
call plot(aa,        'A', ca,       'p', trim(fname) // 'a_c.dat')
print *, 'Plotting isentrope data:', trim(fname) // 'b_a.dat'
call plot(beta(:,2), '%', aa,       'A', trim(fname) // 'b_a.dat')

It would be very nice if I could select all lines, then start LiveEasyAlign, align on ,, then add an ignore expression, for instance with <CTRL-I> and ignore all lines that start with print.

How To Align Several Different Things

How would I go about doing two different alignments? For example, given the following coffeescript:

  user: Ember.belongsTo('models.User', key: 'user', embedded: true)
  cost: Ember.belongsTo('models.Cost', key: 'cost', embedded: true)
  booking: Ember.belongsTo('models.Booking', key: 'booking', embedded: true)
  pageTab: Ember.belongsTo('models.pageTab', key: 'page_tab_id')

I'd like to first align the keys, then align the arguments in Ember.belongsTo, like so:

  user:    Ember.belongsTo('models.User',    key: 'user',    embedded: true)
  cost:    Ember.belongsTo('models.Cost',    key: 'cost',    embedded: true)
  booking: Ember.belongsTo('models.Booking', key: 'booking', embedded: true)
  pageTab: Ember.belongsTo('models.PageTab', key: 'page_tab_id')

Feature request/idea: Realtime interactive mode

I really like this plugin, and the interactive mode is very useful!

One thing that would be very cool, though, would be to have a realtime interactive mode. With this I mean that the selected table/lines would be aligned in realtime in an interactive mode. Something like:

1. Select lines to be aligned
2. Start EasyAlignRealTime (or whatever)
3. Specify delimiter -> table is aligned at once, but we're still in interactive mode
4. Change delimiter/alignment mode -> table updated at once, still in interactive mode
5. Change options -> table updated at once, still in interactive mode
6. Bonus: Add delimiter/alignment mode (first align everything, then for instance change one column if desired)
7. Continue to change until table looks as desired, then exit interactive mode

I don't know how involved this is, but I noticed that I have already often needed several attempts to tweak my desired aligning. I think it could be very useful to tweak in realtime.

Difference with competitiors

I think it's a good idea to specify in README how does this module differ from it's competitors (f.i. tabular)

Error in doc file

Hi @junegunn!

Thanks for a nice plugin :). The latest version has an incorrect help file with tag: "easy-align-examples" occuring twice. It results in E154: Duplicate tag when the :helptags has been performed.

All the best

szw

weird break

I found a break at autoload/easy_align.vim line 846, without while or for statement.

How to align on ->

For example, in OCaml you often have code like:

match xxx with
| [] -> ...
| x::y::xs -> ...
| _ -> ...

How would I align on the -> token using this plugin?

Unknow delimiter key "working"

Hello,

The One-minute guide works for me, but not as showed in the initial gif animation.
I receive the error Unknow delimiter key: x 4 times, where x is {g,a,i,p}
and EasyAlign(_) isn't populated.

vim 7.4.540
urxvt 9.2

Edit: Oh, my bad. That's more easy than I tought, awesome.

Aligning ruby dsl

When using ruby in a DSL like way, I'd like to align:

many_to_one :workspace

many_to_many :resources,
           :join_table => :asset_resources

to:

many_to_one           :workspace

many_to_many          :resources,
                      :join_table => :asset_resources

I'd like to specify the column where to align the semi colon.

How can I do that?

Using <enter> as a normal mode mapping

Hi, great plugin, thanks for creating it.

I have a question about the mappings. I'd like both visual and normal mode mappings to use the same key.
At first I thought that could be <enter> so I had these mappings:

vmap <Enter> <Plug>(EasyAlign)
nmap <Enter> <Plug>(EasyAlign)

I quickly realized how foolish is that. After opening a quickfix window I couldn't select a file (because enter was remapped). Doh.

I've since started using pipe character | for both visual and normal mode. But that's not as nice as enter, especially since this plugin also uses enter for right and center alignment.

So a question: do you know of a way to use enter mapping for normal mode but in a way that it does not mess up quicklist?
Also, are there other scenarios where nmap <enter> would be an issue? (if yes, is there a way around it?)

Thanks for the help!

Aligning on #, Perl/Python/Ruby comments

Hi, is there any reason # isn't a default alignment? Seems very useful.

I tried using both # and # as a regexp, neither worked. Any idea how to align # comments?

Thank you!

Visual selection becomes invisible on <c-l>, <c-r>, <c-o> and <c-/>

Selecting range of N-th delimiter

Hi,

Is it possible to select a range of delimiter, for example the 1st and 2nd delimiter without having to repeat the EasyAlign command for each delimiter?

Ignore custom lines

I wanted to use easy-align on a LaTeX table that looks like this:

\begin{tabular}{lrr}
    \toprule
    Parameter & & Value \\
    \midrule
    $p_0$ & & \SI{8}{bar} \\
    $T_0$ & & \SI{30}{\degreeCelsius} \\ \\

    \multicolumn{3}{l}{Some text} \\
    Component & Amount [\si{kg/h}] & Amount [\%] \\
    \midrule
    \CO   &  \num{33111} & \num{4.80} \\
    N$_2$ & \num{333} & \num{77.06} \\
    O$_2$ &  \num{333391} & \num{16.83} \\
    Argon &   \num{1122} & \num{1.31} \\
    \bottomrule
\end{tabular}

However, \multicolumn kind of screws this up by making the first column way to wide. I was wondering if it would be possible to add more options to a given pattern to ignore certain kinds of lines, for instance in this case to ignore lines with \multiline.

Align on '//'

Having some trouble aligning javascript comments like so:

var clientId      = null;     // chrome extension address
var connection    = null;   // connection to the mooltipass
var connected     = false;   // current connection state
var version       = 'unknown'; // connected mooltipass version
var authReq       = null;      // current authentication request

I tried the regexps //, \/\/, \\/\\/ and \\\/\\\/

Add single/double quotation mark as delimiters

I added 's': { 'pattern': "'" } and 'd': { 'pattern': '"' } to g:easy_align_delimiters, however it doesn't work, any suggestions?

Alignment with tabs inserting spaces still

Think I found an edge-case

Running :EasyAlign= on this (_ spaces in indent area, » tabs in indentation)

»   »   n2f = {}
»   »   n2v = {}
»   »   f2v = {}
»   »   n2gv = {}
»   »   n2vt = {}

Yeilds this

_»  »   n2f  = {}
_»  »   n2v  = {}
_»  »   f2v  = {}
_»  »   n2gv = {}
_»  »   n2vt = {}

Better documentation: Table of contents

The documentation is quite good, but it lacks a table of contents to make it easier to find what your looking for.

Add key to toggle live mode

How about a special keystroke, such as i (perhaps too naive, say <c-i>) that allows one to enter interactive mode after <plug>easyalign? In this way one can halve the mappings needed to invoke easyalign in all its variants.

Alias for EasyAlign?

I found it not so easy to type EasyAlign full, with the shifts and so on.

Is there a possibility to have a alias. Like

<,'>Ea=

instead

<,'>EasyAlign=

Regex align [A-Z] not different from [a-z]

Shouldn't this follow regular expression rules and differentiate on letter case?

Given the following unformatted SQL:

SELECT tt.something,
tt.something_else,
tot.something,
tot.something_else
FROM this_table tt
JOIN this_other_table tot
ON tot.table = tt.table

I'd like the following final result:

SELECT tt.something,
       tt.something_else,
       tot.something,
       tot.something_else
  FROM this_table tt
  JOIN this_other_table tot
    ON tot.table = tt.table

However, the command :EasyAlign /[A-Z]*/ matches lower and upper case, providing the following:

SELECT tt.something,
    tt .something_else,
   tot .something,
   tot .something_else
  FROM this_table tt
  JOIN this_other_table tot
    ON tot.table = tt.table

The command :EasyAlign /[a-z]*/ provides the same results:

SELECT tt.something,
    tt .something_else,
   tot .something,
   tot .something_else
  FROM this_table tt
  JOIN this_other_table tot
    ON tot.table = tt.table

Vim Throws "using floating point as string"

The error message refers to do_align at:

 { 'pivot_len': 0.0, 'token_len': 0, 'just_len': 0, 'delim_len': 0, 'indent': 0, 'tokens': 0, 'strip_len': 0 }

The error message disappears, when I change 0.0 to '0.0' in the named function, but of course then the alignment does not work at all. I also tried with an integer instead of a float with the same result as with the string.

What I did:

1. install easy-align with pathogen as described in the Readme.
2. add the mappings according to the Readme to my .vim file.
3. open DEMO.md from the package
4. move the cursor to George Harrison
5. vip <Enter> <Space>

I use Vim 7.3.547 on Ubuntu Linux. I also have lightline and fugitive installed.

What am I missing?

:EasyAlign command not aligning selected text. Am I missing something?

I expected text to be aligned with these operations, but the text was not changed, while no error was raised.

Am I missing something?

1. Select a chunk of text with visual mode

   language_model translation_table
   test_set test_references
   tune_set tune_references
   

2. (to suppress other plugin as possible), call :'<,'>EasyAlign \␣

I'm using MacVIM 7.4, if that matters.

Thanks!

Suggestion for improved interface

I do like the plugin, but after some testing and wanting to align a paragraph after --> as column delimiter, I couldn't find out how. So i thought: why not let the liveEditing accept any string as delimiter followed by and then match the lines according to the string entered.

Alignment is funky when indentation method is tabs.

If you're using tabs to indent instead of spaces the functionality is strange.

Ex (» denotes beginning of tab)

»   »   a = 1
»   »   »   b =2
»   »   »   c = 4
»   »   »   »   f=4

Running :EasyAlign= results in this

»   »   a   = 1
»   »   »   b  = 2
»   »   »   c  = 4
»   »   »   »   f = 4

Running an align on = using shallow or deep indentation removes tabs and uses spaces. Ex:

  a = 1
  b = 2
  c = 4
  f = 4

Silent mappings

Following your recommendation here I have the following mapping:

nmap <Leader>& mz<Plug>(EasyAlign)ip*&`z

When calling the mapping I would like to suppress the

:EasyAlign *&

message that is returned in the command line (as seen in the image)
Is there a way to do this? I tried adding <silent> to the mapping definition but it does not work.
Thanks!! (awesome plugin btw)

How to use recursive alignment?

Hey! I saw the last commit implementing recursive alignment (if I read right).

I get it right, it should be able to help transform something like:

class Offer
  include DataMapper::Resource

  property :id, serial
  property :title, string, required: true
  property :description, text, required: true
  property :company_name, text, required: true
  property :company_logo, string, length: 250
  property :location, text, required: true
  property :starting_date, datetime
  property :created_at, datetime

end

Into something like:

class Offer
  include DataMapper::Resource

  property :id,            serial
  property :title,         string, required: true
  property :description,   text,   required: true
  property :company_name,  text,   required: true
  property :company_logo,  string, length: 250
  property :location,      text,   required: true
  property :starting_date, datetime
  property :created_at,    datetime

end

Am I right? If so, I'd like to know how to use it. If not, can someone explain to me what I missed? :)

For the record, all I've managed to get is:

class Offer
  include DataMapper::Resource

  property :id,            serial
  property :title,         string, required: true
  property :description,   text, required: true
  property :company_name,  text, required: true
  property :company_logo,  string, length: 250
  property :location,      text, required: true
  property :starting_date, datetime
  property :created_at,    datetime

end