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

Convert current README.md into helpfile. Added TOC (#22)

Browse Source
This commit is contained in:
Junegunn Choi
2013-12-08 00:06:42 +09:00
parent 6d85e93476
commit b8e93f96b8
2 changed files with 703 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@@ -59,7 +59,7 @@ Add the following mappings to your .vimrc.
vmap <Enter> <Plug>(EasyAlign) vmap <Enter> <Plug>(EasyAlign)
" Start interactive EasyAlign with a Vim movement " Start interactive EasyAlign with a Vim movement
nmap <leader>a <Plug>(EasyAlign) nmap <Leader>a <Plug>(EasyAlign)
``` ```
And with the following lines of text, And with the following lines of text,
@@ -76,16 +76,14 @@ 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=` - `<Leader>aip=`
- Start EasyAlign command (`<Leader>a`) for `i`nner `p`aragraph - Start EasyAlign command (`<Leader>a`) 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](https://github.com/tpope/vim-repeat). [repeat.vim](https://github.com/tpope/vim-repeat). Install
[visualrepeat](https://github.com/vim-scripts/visualrepeat) as well if you want
If you want to repeat the previous alignment for the selected range in visual to repeat in visual mode. Or you can add the following mapping to your .vimrc.
mode, install [visualrepeat](https://github.com/vim-scripts/visualrepeat)
(recommended) or add the following mapping to your .vimrc.
```vim ```vim
" Repeat alignment in visual mode with . key " Repeat alignment in visual mode with . key
@@ -108,7 +106,7 @@ variant `:EasyAlign!`).
### Concept of _alignment rule_ ### 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
@@ -117,8 +115,14 @@ several options, you can just type in a single character.
### Interactive mode ### Interactive mode
The command will go into the interactive mode when no argument is given. The command will go into the interactive mode when no argument is given.
For convenience, it is advised that you define mappings for triggering it in
your `.vimrc`. ```vim
:EasyAlign
```
However, it is strongly advised that you define mappings for triggering it in
your `.vimrc` as follows. (Of course you can use any key combination as the
trigger.)
```vim ```vim
" For visual mode (e.g. vip<Enter>) " For visual mode (e.g. vip<Enter>)
@@ -128,12 +132,18 @@ vmap <Enter> <Plug>(EasyAlign)
nmap <Leader>a <Plug>(EasyAlign) nmap <Leader>a <Plug>(EasyAlign)
``` ```
(Of course you can use any key combination as the trigger.) The advantages of using the above mappings are two-fold:
- They require less keystrokes
- They make alignments repeatable with
[repeat.vim](https://github.com/tpope/vim-repeat) and
[visualrepeat](https://github.com/vim-scripts/visualrepeat)
With the mapping, you can align selected lines of text with only a few keystrokes. With the mapping, you can align selected lines of text with only a few keystrokes.
1. `<Enter>` key (or `<Leader>a` followed by a Vim movement) to start 1. `<Enter>` key in visual mode, or `<Leader>a` followed by a Vim movement to
interactive EasyAlign command start interactive EasyAlign command
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)
- `1` Around the 1st occurrences of delimiters - `1` Around the 1st occurrences of delimiters
@@ -144,19 +154,19 @@ With the mapping, you can align selected lines of text with only a few keystroke
- `-` 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>`, `=`, `:`, `.`, `|`, `&`, `,`)
Alignment rules for the following delimiters have been defined to meet the most needs. Alignment rules for the following delimiters have been defined to meet the most needs.
| 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 `\\`) |
| &#124; | Table markdown | | `<Bar>` | Table markdown |
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 `g:easy_align_delimiters`, which will be described in
@@ -164,21 +174,21 @@ You can override these default rules or define your own rules with
#### Example command sequences #### Example command sequences
| With visual map | Description | Equivalent command | | With visual map | Description | Equivalent command |
| ------------------- | ------------------------------------------------------- | ---------------------- | | ------------------- | ---------------------------------- | ---------------------- |
| `<Enter><space>` | Alignment around 1st whitespaces | `:'<,'>EasyAlign\ ` | | `<Enter><Space>` | Around 1st whitespaces | `:'<,'>EasyAlign\ ` |
| `<Enter>2<space>` | Alignment around 2nd whitespaces | `:'<,'>EasyAlign2\ ` | | `<Enter>2<Space>` | Around 2nd whitespaces | `:'<,'>EasyAlign2\ ` |
| `<Enter>-<space>` | Alignment around the last whitespaces | `:'<,'>EasyAlign-\ ` | | `<Enter>-<Space>` | Around the last whitespaces | `:'<,'>EasyAlign-\ ` |
| `<Enter>-2<space>` | Alignment around the 2nd to last whitespaces | `:'<,'>EasyAlign-2\ ` | | `<Enter>-2<Space>` | Around the 2nd to last whitespaces | `:'<,'>EasyAlign-2\ ` |
| `<Enter>:` | Alignment around 1st colon (`key: value`) | `:'<,'>EasyAlign:` | | `<Enter>:` | Around 1st colon (`key: value`) | `:'<,'>EasyAlign:` |
| `<Enter><Right>:` | Alignment around 1st colon (`key : value`) | `:'<,'>EasyAlign:s0l1` | | `<Enter><Right>:` | Around 1st colon (`key : value`) | `:'<,'>EasyAlign:s0l1` |
| `<Enter>=` | Alignment around 1st operators with = | `:'<,'>EasyAlign=` | | `<Enter>=` | Around 1st operators with = | `:'<,'>EasyAlign=` |
| `<Enter>2=` | Alignment around 2nd operators with = | `:'<,'>EasyAlign2=` | | `<Enter>2=` | Around 2nd operators with = | `:'<,'>EasyAlign2=` |
| `<Enter>3=` | Alignment around 3rd operators with = | `:'<,'>EasyAlign3=` | | `<Enter>3=` | Around 3rd operators with = | `:'<,'>EasyAlign3=` |
| `<Enter>*=` | Alignment around all operators with = | `:'<,'>EasyAlign*=` | | `<Enter>*=` | Around all operators with = | `:'<,'>EasyAlign*=` |
| `<Enter>**=` | Left-right alternating alignment around all = operators | `:'<,'>EasyAlign**=` | | `<Enter>**=` | Left-right alternating around = | `:'<,'>EasyAlign**=` |
| `<Enter><Enter>=` | Right alignment around 1st equals signs | `:'<,'>EasyAlign!=` | | `<Enter><Enter>=` | Right alignment around 1st = | `:'<,'>EasyAlign!=` |
| `<Enter><Enter>**=` | Right-left alternating alignment around all = operators | `:'<,'>EasyAlign!**=` | | `<Enter><Enter>**=` | Right-left alternating around = | `:'<,'>EasyAlign!**=` |
#### Using regular expressions #### Using regular expressions
@@ -198,7 +208,7 @@ 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](https://github.com/junegunn/vim-easy-align#alignment-options).
| Key | Option | Values | | Key | Option | Values |
| -------- | ------------------ | -------------------------------------------------- | | --------- | ------------------ | -------------------------------------------------- |
| `CTRL-F` | `filter` | Input string (`[gv]/.*/?`) | | `CTRL-F` | `filter` | Input string (`[gv]/.*/?`) |
| `CTRL-I` | `indentation` | shallow, deep, none, keep | | `CTRL-I` | `indentation` | shallow, deep, none, keep |
| `CTRL-L` | `left_margin` | Input number or string | | `CTRL-L` | `left_margin` | Input number or string |
@@ -224,7 +234,7 @@ With normal-mode map to `<Plug>(EasyAlign)`, EasyAlign command becomes a Vim
operator that can be used with any Vim movement. operator that can be used with any Vim movement.
```vim ```vim
nmap <leader>a <Plug>(EasyAlign) nmap <Leader>a <Plug>(EasyAlign)
``` ```
Now without going into visual mode, you can align the lines in the paragraph Now without going into visual mode, you can align the lines in the paragraph
@@ -243,8 +253,8 @@ the same parameters as `:EasyAlign`. I suggest you define mappings such as
follows in addition to the ones for `:EasyAlign` command. follows in addition to the ones for `:EasyAlign` command.
```vim ```vim
vmap <leader><Enter> <Plug>(LiveEasyAlign) vmap <Leader><Enter> <Plug>(LiveEasyAlign)
nmap <leader>A <Plug>(LiveEasyAlign) nmap <Leader>A <Plug>(LiveEasyAlign)
``` ```
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
@@ -304,17 +314,17 @@ notation.
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 | `s[01]` | | `stick_to_left` | `s[01]` |
| ignore_unmatched | `iu[01]` | | `ignore_unmatched` | `iu[01]` |
| ignore_groups | `ig\[.*\]` | | `ignore_groups` | `ig\[.*\]` |
| delimiter_align | `d[lrc]` | | `delimiter_align` | `d[lrc]` |
| mode_sequence | `m[lrc*]*` | | `mode_sequence` | `m[lrc*]*` |
| indentation | `i[ksdn]` | | `indentation` | `i[ksdn]` |
For your information, the same thing can be done in the interactive mode as well For your information, the same thing can be done in the interactive mode as well
with the following key combination. with the following key combination.
@@ -691,7 +701,7 @@ 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 can extend the rules by setting a dictionary named `g:easy_align_delimiters`.
You may refer to the definitions of the default alignment rules You may refer to the definitions of the default alignment rules
[here](https://github.com/junegunn/vim-easy-align/blob/2.6.1/autoload/easy_align.vim#L29). [here](https://github.com/junegunn/vim-easy-align/blob/2.9.0/autoload/easy_align.vim#L29).
#### Example #### Example
@@ -789,7 +799,7 @@ It even feels like a native Vim command!
- *Right-align*: `<Enter><Enter>` - *Right-align*: `<Enter><Enter>`
- around the *second* occurrences: `2` - around the *second* occurrences: `2`
- of *whitespaces*: `<space>` - of *whitespaces*: `<Space>`
For the simplest cases, Tabular and Align are also easy to use. But sooner or 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 later, you will find yourself scratching your head, trying to come up with some

946
doc/easy_align.txt
View File

File diff suppressed because it is too large Load Diff