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

Update README (#68)

Browse Source 
- Split the long demo into short gifs
- Clarify the modes of execution
This commit is contained in:
Junegunn Choi
2015-10-09 17:57:01 +09:00
parent 0db4ea6132
commit ed65b47f1b
1 changed files with 151 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
README.md
View File

@@ -3,29 +3,12 @@ vim-easy-align ![travis-ci](https://travis-ci.org/junegunn/vim-easy-align.svg?br
A simple, easy-to-use Vim alignment plugin. A simple, easy-to-use Vim alignment plugin.
Demo ![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/equals.gif)
----
<img src="https://raw.githubusercontent.com/junegunn/i/master/vim-easy-align.gif" height="494" alt="Screencast">
(Too fast? Slower GIF is [here](https://raw.githubusercontent.com/junegunn/i/master/vim-easy-align-slow.gif))
Features
--------
- Easy to use
- Comes with a predefined set of alignment rules
- Provides a fast and intuitive interface
- Extensible
- You can define your own rules
- Supports arbitrary regular expressions
- Optimized for code editing
- Takes advantage of syntax highlighting feature to avoid unwanted alignments
Installation Installation
------------ ------------
User your favorite plugin manager. Use your favorite plugin manager.
Using [vim-plug](https://github.com/junegunn/vim-plug): Using [vim-plug](https://github.com/junegunn/vim-plug):
@@ -33,20 +16,20 @@ Using [vim-plug](https://github.com/junegunn/vim-plug):
Plug 'junegunn/vim-easy-align' Plug 'junegunn/vim-easy-align'
``` ```
TL;DR - One-minute guide Quick start guide
------------------------ -----------------
Add the following mappings to your .vimrc. Add the following mappings to your .vimrc.
```vim ```vim
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>) " Start interactive EasyAlign in visual mode (e.g. vipga)
vmap <Enter> <Plug>(EasyAlign) xmap ga <Plug>(EasyAlign)
" Start interactive EasyAlign for a motion/text object (e.g. gaip) " Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap ga <Plug>(EasyAlign) nmap ga <Plug>(EasyAlign)
``` ```
And with the following lines of text, Then with the following lines of text,
``` ```
apple =red apple =red
@@ -56,80 +39,107 @@ sky-= blue
try these commands: try these commands:
- `vip<Enter>=` - `vipga=`
- `v`isual-select `i`nner `p`aragraph - `v`isual-select `i`nner `p`aragraph
- Start EasyAlign command (`<Enter>`) - Start EasyAlign command (`ga`)
- Align around `=` - Align around `=`
- `gaip=` - `gaip=`
- Start EasyAlign command (`ga`) 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 Demo
[repeat.vim](https://github.com/tpope/vim-repeat). Install ----
[visualrepeat](https://github.com/vim-scripts/visualrepeat) as well if you want
to repeat in visual mode. ### 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 `,`.
#### `=`
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/equals.gif)
- `=` Around the 1st occurrences
- `2=` Around the 2nd occurrences
- `*=` Around all occurrences
- `**=` Left/Right alternating alignment around all occurrences
- `<Enter>` Toggling left/right/center alignment mode
#### `<Space>`
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/spaces.gif)
- `<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
#### `,`
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/commas.gif)
- 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
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/regex.gif)
You can use an arbitrary regular expression instead
- by pressing `<Ctrl-X>` in interactive mode
- or using `:EasyAlign /REGEX/` command
### Different ways to start
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/modes.gif)
This demo shows how you can start interative mode with visual selection or use
non-interactive `:EasyAlign` command.
### Aligning table cells
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/tables.gif)
Check out various alignment options and "live interative mode".
### Syntax-aware alignment
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/yaml.gif)
Delimiters in strings and comments are ignored by default.
### Using blockwise-visual mode
![](https://raw.githubusercontent.com/junegunn/i/master/easy-align/blockwise-visual.gif)
You can limit the scope with blockwise-visual mode.
Usage Usage
----- -----
### Concept of _alignment rule_ ### Flow of execution
Though easy-align can align lines of text around any delimiter, it provides <img src="https://raw.githubusercontent.com/junegunn/i/master/easy-align/usage.png" width="469">
shortcuts for the most common use cases with the concept of "_alignment rule_".
An *alignment rule* is a predefined set of options for common alignment tasks,
which is identified by a single character, *DELIMITER KEY*, such as `<Space>`,
`=`, `:`, `.`, `|`, `&`, `#`, and `,`.
Think of it as a shortcut. Instead of writing regular expression and setting
several options, you can just type in a single character.
### Execution models
There are two ways to use easy-align. There are two ways to use easy-align.
#### 1. Using `<Plug>` mappings #### 1. `<Plug>` mappings (interactive mode)
The recommended method is to use `<Plug>` mappings as described earlier. 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
| Mapping | Mode | Description | sequences.
| ----------------------- | ------ | ---------------------------------------------------- |
| `<Plug>(EasyAlign)` | normal | Start interactive mode for a motion/text object |
| `<Plug>(EasyAlign)` | visual | Start interactive mode for the selection |
| `<Plug>(LiveEasyAlign)` | normal | Start live-interactive mode for a motion/text object |
| `<Plug>(LiveEasyAlign)` | visual | Start live-interactive mode for the selection |
#### 2. Using `:EasyAlign` command
If you prefer command-line or do not want to start interactive mode, you can use
`:EasyAlign` command instead.
| Mode | Command |
| ------------------------------------------ | ------------------------------------------------ |
| Interactive mode | `:EasyAlign[!] [OPTIONS]` |
| Live interactive mode | `:LiveEasyAlign[!] [...]` |
| Non-interactive mode (predefined rules) | `:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]` |
| Non-interactive mode (regular expressions) | `:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]` |
### Interactive mode
The following sections will assume that you have `<Plug>(EasyAlign)` mappings in
your .vimrc as below:
```vim ```vim
" Start interactive EasyAlign in visual mode (e.g. vip<Enter>)
vmap <Enter> <Plug>(EasyAlign)
" Start interactive EasyAlign for a motion/text object (e.g. gaip)
nmap ga <Plug>(EasyAlign) nmap ga <Plug>(EasyAlign)
xmap ga <Plug>(EasyAlign)
``` ```
With these mappings, you can align text with only a few keystrokes. 1. `ga` key in visual mode, or `ga` 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 cycle between alignment mode (left, right, or center)
1. Optional: N-th delimiter (default: 1) 1. (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
- ... - ...
@@ -138,12 +148,27 @@ With these mappings, you can align text with only a few keystrokes.
- `-` 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
- ... - ...
1. Delimiter key (a single keystroke; `<Space>`, `=`, `:`, `.`, `|`, `&`, `#`, `,`) 1. Delimiter key (a single keystroke; `<Space>`, `=`, `:`, `.`, `|`, `&`, `#`, `,`) or an arbitrary regular expression followed by `<CTRL-X>`
#### Predefined alignment rules #### 2. Using `:EasyAlign` command
| Delimiter key | Description/Use cases | If you prefer command-line, use `:EasyAlign` command instead.
| ------------- | -------------------------------------------------------------------- |
```vim
" 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 | | `<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 |
@@ -153,43 +178,41 @@ With these mappings, you can align text with only a few keystrokes.
| `#` | Ruby/Python comments | | `#` | Ruby/Python comments |
| `<Bar>` | Table markdown | | `<Bar>` | Table markdown |
You can override these default rules or define your own rules with You can also define your own rules with `g:easy_align_delimiters` which will
`g:easy_align_delimiters`, which will be described in be described in [the later section](#extending-alignment-rules).
[the later section](https://github.com/junegunn/vim-easy-align#extending-alignment-rules).
#### Examples ----
| With visual map | Description | Equivalent command | ### Interactive mode
| ------------------- | ---------------------------------- | --------------------- |
| `<Enter><Space>` | Around 1st whitespaces | `:'<,'>EasyAlign\ ` |
| `<Enter>2<Space>` | Around 2nd whitespaces | `:'<,'>EasyAlign2\ ` |
| `<Enter>-<Space>` | Around the last whitespaces | `:'<,'>EasyAlign-\ ` |
| `<Enter>-2<Space>` | Around the 2nd to last whitespaces | `:'<,'>EasyAlign-2\ ` |
| `<Enter>:` | Around 1st colon (`key: value`) | `:'<,'>EasyAlign:` |
| `<Enter><Right>:` | Around 1st colon (`key : value`) | `:'<,'>EasyAlign:<l1` |
| `<Enter>=` | Around 1st operators with = | `:'<,'>EasyAlign=` |
| `<Enter>3=` | Around 3rd operators with = | `:'<,'>EasyAlign3=` |
| `<Enter>*=` | Around all operators with = | `:'<,'>EasyAlign*=` |
| `<Enter>**=` | Left-right alternating around = | `:'<,'>EasyAlign**=` |
| `<Enter><Enter>=` | Right alignment around 1st = | `:'<,'>EasyAlign!=` |
| `<Enter><Enter>**=` | Right-left alternating around = | `:'<,'>EasyAlign!**=` |
#### Using regular expressions Interactive mode is started either with `<Plug>(EasyAlign)` mapping or with
`:EasyAlign` command with no argument.
Instead of finishing the command with a predefined delimiter key, you can type #### Examples using predefined rules
in a regular expression after `<CTRL-/>` or `<CTRL-X>` key.
For example, if you want to align text around all occurrences of numbers:
- `<Enter>` | Keystrokes | Description | Equivalent command |
- `*` | ------------ | ---------------------------------- | --------------------- |
- `<CTRL-X>` | `<Space>` | Around 1st whitespaces | `:'<,'>EasyAlign\ ` |
- `[0-9]\+` | `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 #### Alignment options in interactive mode
While in interactive mode, you can set alignment options using special shortcut While in interactive mode, you can set alignment options using special shortcut
keys listed below. The meaning of each option will be described in keys listed below. The meaning of each option will be described in
[the following sections](https://github.com/junegunn/vim-easy-align#alignment-options). [the following sections](#alignment-options).
| Key | Option | Values | | Key | Option | Values |
| --------- | ------------------ | -------------------------------------------------- | | --------- | ------------------ | -------------------------------------------------- |
@@ -199,13 +222,13 @@ keys listed below. The meaning of each option will be described in
| `CTRL-R` | `right_margin` | Input number or string | | `CTRL-R` | `right_margin` | Input number or string |
| `CTRL-D` | `delimiter_align` | left, center, right | | `CTRL-D` | `delimiter_align` | left, center, right |
| `CTRL-U` | `ignore_unmatched` | 0, 1 | | `CTRL-U` | `ignore_unmatched` | 0, 1 |
| `CTRL-G` | `ignore_groups` | [], ['String'], ['Comment'], ['String', 'Comment'] | | `CTRL-G` | `ignore_groups` | `[]`, `['String']`, `['Comment']`, `['String', 'Comment']` |
| `CTRL-A` | `align` | Input string (`/[lrc]+\*{0,2}/`) | | `CTRL-A` | `align` | Input string (`/[lrc]+\*{0,2}/`) |
| `<Left>` | `stick_to_left` | `{ 'stick_to_left': 1, 'left_margin': 0 }` | | `<Left>` | `stick_to_left` | `{ 'stick_to_left': 1, 'left_margin': 0 }` |
| `<Right>` | `stick_to_left` | `{ 'stick_to_left': 0, 'left_margin': 1 }` | | `<Right>` | `stick_to_left` | `{ 'stick_to_left': 0, 'left_margin': 1 }` |
| `<Down>` | `*_margin` | `{ 'left_margin': 0, 'right_margin': 0 }` | | `<Down>` | `*_margin` | `{ 'left_margin': 0, 'right_margin': 0 }` |
### Live interactive mode #### Live interactive mode
If you're performing a complex alignment where multiple options should be 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
@@ -215,15 +238,15 @@ Live interactive mode can be started with either `<Plug>(LiveEasyAlign)` map
or `:LiveEasyAlign` command. Or you can switch to live interactive mode while or `:LiveEasyAlign` command. Or you can switch to live interactive mode while
in ordinary interactive mode by pressing `<CTRL-P>`. (P for Preview) 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
regular expression) again to finalize the alignment. This allows you to preview `<CTRL-X>` on regular expression) again to finalize the alignment. This allows
the result of the alignment and freely change the delimiter using backspace key you to preview the result of the alignment and freely change the delimiter
without leaving the interactive mode. using backspace key without leaving the interactive mode.
### Non-interactive mode ### :EasyAlign command
Instead of starting interactive mode, you can use declarative, non-interactive Instead of starting interactive mode, you can use non-interactive `:EasyAlign`
`:EasyAlign` command. command.
```vim ```vim
" Using predefined alignment rules " Using predefined alignment rules
@@ -242,8 +265,7 @@ Instead of starting interactive mode, you can use declarative, non-interactive
``` ```
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](https://github.com/junegunn/vim-easy-align#alignment-options), detail later](#alignment-options), in Vim dictionary format.
in Vim dictionary format.
- `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }` - `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }`
@@ -254,11 +276,11 @@ left. So we get:
apple;: banana:: cake apple;: banana:: cake
data;; exchange:; format data;; exchange:; format
Option names are fuzzy-matched, so you can write as follows: You don't have to write complete names as long as they're distinguishable.
- `:EasyAlign * /[:;]\+/ { 'stl': 1, 'l': 0 }` - `:EasyAlign * /[:;]\+/ { 'stl': 1, 'l': 0 }`
You can even omit spaces between the arguments, so concisely (or cryptically): You can even omit spaces between the arguments.
- `:EasyAlign*/[:;]\+/{'s':1,'l':0}` - `:EasyAlign*/[:;]\+/{'s':1,'l':0}`
@@ -281,15 +303,6 @@ The following table summarizes the shorthand notation.
| `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
follows:
- `<Enter>`
- `*`
- `<Left>`
- `<CTRL-X>`
- `[:;]\+`
### Partial alignment in blockwise-visual mode ### Partial alignment in blockwise-visual mode
In blockwise-visual mode (`CTRL-V`), EasyAlign command aligns only the selected In blockwise-visual mode (`CTRL-V`), EasyAlign command aligns only the selected