vim-easy-align/doc/easy_align.txt

vim-easy-align                              *vim-easy-align* *easy-align*
=========================================================================

A simple, easy-to-use Vim alignment plugin without too much ambition.

  Author: Junegunn Choi
  Source: https://github.com/junegunn/vim-easy-align


EasyAlign                                                     *EasyAlign*
-------------------------------------------------------------------------

vim-easy-align defines interactive `:EasyAlign` command in the visual mode.

For convenience, it is advised that you define a mapping for triggering it
in your `.vimrc`.

    vnoremap <silent> <Enter> :EasyAlign<cr>

With this mapping, you can align selected lines with a few keystrokes.

1. <Enter> key to start interactive EasyAlign command
2. Optional Enter keys to switch justficiation mode (default: left)
3. Optional field number (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>  General alignment around whitespaces
    =        Operators containing equals sign (=, ==, !=, +=, &&=, ...)
    :        Suitable for formatting JSON or YAML
    .        Multi-line method chaining
    ,        Multi-line method arguments. CSV.
    |        Table markdown

During the key sequence, <Enter> key will toggle right-justification mode.

Examples:

  <Enter><space>     Alignment around 1st whitespaces
  <Enter>2<space>    Alignment around 2nd whitespaces
  <Enter>-<space>    Alignment around the last whitespaces
  <Enter>:           Alignment around 1st colon
  <Enter>=           Alignment around 1st equals signs (and the likes)
  <Enter>2=          Alignment around 2nd equals signs (and the likes)
  <Enter>3=          Alignment around 3rd equals signs (and the likes)
  <Enter>*=          Alignment around all equals signs (and the likes)
  <Enter>**=         Left-right alternating alignment around all equals signs
  <Enter><Enter>=    Right-justified alignment around 1st equals signs
  <Enter><Enter>**=  Right-left alternating alignment around all equals signs


EasyAlignRight                                           *EasyAlignRight*
-------------------------------------------------------------------------

EasyAlignRight is the right-justified version of EasyAlign command.


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.


Ignoring delimiters in comments or strings         *g:easy_align_ignores*
-------------------------------------------------------------------------

EasyAlign can be configured to ignore delimiters in certain highlight
groups, such as code comments or strings. By default, delimiters that are
highlighted as code comments or strings are ignored.

    " Default:
    "   If a delimiter is in a highlight group whose name matches
    "   any of the followings, it will be ignored.
    let g:easy_align_ignores = ['Comment', 'String']

For example,

    {
      # Quantity of apples: 1
      apple: 1,
      # Quantity of bananas: 2
      bananas: 2,
      # Quantity of grape:fruits: 3
      'grape:fruits': 3
    }

becomes

    {
      # Quantity of apples: 1
      apple:          1,
      # Quantity of bananas: 2
      bananas:        2,
      # Quantity of grape:fruits: 3
      'grape:fruits': 3
    }

You can override `g:easy_align_ignores` to change the rule.

    let g:easy_align_ignores = []

Then you get,

    {
      # Quantity of apples:  1
      apple:                 1,
      # Quantity of bananas: 2
      bananas:               2,
      # Quantity of grape:   fruits: 3
      'grape:                fruits': 3
    }


Handling unmatched lines                  *g:easy_align_ignore_unmatched*
-------------------------------------------------------------------------

Lines without a matching delimiter are ignored as well (except in
right-justification mode).

For example, when aligning the following code block around the 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, this default behavior is also configurable.

    let g:easy_align_ignore_unmatched = 0

Then we get,

    {
      apple:                             proc {
        this_line_does_not_have_a_colon
      },
      bananas:                           2,
      grapefruits:                       3
    }


Extending alignment rules                       *g:easy_align_delimiters*
-------------------------------------------------------------------------

    let g:easy_align_delimiters = {
    \ '>': { 'pattern': '>>\|=>\|>' },
    \ '/': { 'pattern': '//\+' },
    \ '#': { 'pattern': '#\+' },
    \ ']': {
    \     'pattern':       '[\[\]]',
    \     'margin_left':   '',
    \     'margin_right':  '',
    \     'stick_to_left': 0
    \   },
    \ ')': {
    \     'pattern':       '[()]',
    \     'margin_left':   '',
    \     'margin_right':  '',
    \     'stick_to_left': 0
    \   }
    \ }