From edba1827ed6b94bed8a2e461087d1853b91f9a57 Mon Sep 17 00:00:00 2001 From: Junegunn Choi Date: Wed, 7 Aug 2013 00:30:34 +0900 Subject: [PATCH] Update doc --- README.md | 27 +++++++++++----------- doc/easy_align.txt | 57 ++++++++++++++++++++++++++++++---------------- 2 files changed, 50 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 0eae2fe..fb1ba2b 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ your `.vimrc`. vnoremap :EasyAlign ``` -With the mapping, you can align selected lines with a few keystrokes. +With the mapping, you can align selected lines of text with a few keystrokes. 1. `` key to start interactive EasyAlign command 1. Optional Enter keys to toggle right-justification mode @@ -71,14 +71,14 @@ With the mapping, you can align selected lines with a few keystrokes. Alignment rules for the following delimiters have been defined to meet the most needs. -| Delimiter key | Description/Use cases | -| ------------- | ---------------------------------------------------------- | -| `` | General alignment around spaces | -| `=` | Operators containing equals sign (=, ==, !=, +=, &&=, ...) | -| `:` | Suitable for formatting JSON or YAML | -| `.` | Multi-line method chaining | -| `,` | Multi-line method arguments | -| | | Table markdown | +| Delimiter key | Description/Use cases | +| ------------- | -------------------------------------------------------------------- | +| `` | General alignment around whitespaces | +| `=` | Operators containing equals sign (`=`, `==,` `!=`, `+=`, `&&=`, ...) | +| `:` | Suitable for formatting JSON or YAML | +| `.` | Multi-line method chaining | +| `,` | Multi-line method arguments | +| | | Table markdown | #### Example command sequences @@ -142,7 +142,7 @@ You can even omit spaces between the arguments, so concisely (or cryptically): - `:EasyAlign*/[:;]\+/{'s':1,'l':0}` -Available options for each alignment are as follows. +Available options are as follows. | Atrribute | Type | Default | | ---------------- | ---------------- | ----------------------- | @@ -239,7 +239,7 @@ array, let g:easy_align_ignores = [] ``` -or providing `ignores` option to :EasyAlign command +or providing `ignores` option directly to `:EasyAlign` command ```vim :EasyAlign:{'is':[]} @@ -291,14 +291,14 @@ this is usually what we want. However, this default behavior is also configurable. -One way is to set the global `g:easy_align_ignore_unmatched` variable to be 0. +One way is to set the global `g:easy_align_ignore_unmatched` variable to 0. ```vim let g:easy_align_ignore_unmatched = 0 ``` Or in non-interactive mode, you can provide `ignore_unmatched` option to -:EasyAlign command +`:EasyAlign` command as follows. ```vim :EasyAlign:{'iu':0} @@ -324,7 +324,6 @@ you can extend the rules by setting a dictionary named `g:easy_align_delimiters` #### Example ```vim -" Examples let g:easy_align_delimiters = { \ '>': { 'pattern': '>>\|=>\|>' }, \ '/': { 'pattern': '//\+\|/\*\|\*/', 'ignores': ['String'] }, diff --git a/doc/easy_align.txt b/doc/easy_align.txt index c9c4e55..b4152ad 100644 --- a/doc/easy_align.txt +++ b/doc/easy_align.txt @@ -7,10 +7,11 @@ A simple, easy-to-use Vim alignment plugin without too much ambition. Source: https://github.com/junegunn/vim-easy-align -EasyAlign *:EasyAlign* +EasyAlign *:EasyAlign* *:EasyAlign!* ------------------------------------------------------------------------- vim-easy-align defines `:EasyAlign` command in the visual mode. +(:EasyAlign! is the right-justification version.) | Mode | Command | | ------------------------- | ------------------------------------------- | @@ -18,13 +19,17 @@ vim-easy-align defines `:EasyAlign` command in the visual mode. | Using predefined rules | :EasyAlign [FIELD#] DELIMITER_KEY [OPTIONS] | | Using regular expressions | :EasyAlign [FIELD#] /REGEXP/ [OPTIONS] | -The commands will go into the interactive mode when no argument is given. -For convenience, it is advised that you define a mapping for triggering it -in your `.vimrc`. + +Interactive mode +------------------------------------------------------------------------- + +The command will go into the interactive mode when no argument is given. +For convenience, it is advised that you define a mapping for triggering it in +your `.vimrc`. vnoremap :EasyAlign -With this mapping, you can align selected lines with a few keystrokes. +With this mapping, you can align selected lines of text with a few keystrokes. 1. key to start interactive EasyAlign command 2. Optional Enter keys to switch justficiation mode (default: left) @@ -61,24 +66,18 @@ Examples: **= Right-left alternating alignment around all equals signs -EasyAlign! *:EasyAlign!* -------------------------------------------------------------------------- - -:EasyAlign! is the right-justification version of :EasyAlign command. - - Non-interactive mode --------------------- +------------------------------------------------------------------------- Instead of going into the interactive mode, you can type in arguments to `:EasyAlign` command. In non-interactive mode, you can even use arbitrary regular expressions. " Using predefined alignment rules - :EasyAlign [FIELD#] DELIMITER_KEY [OPTIONS] + :EasyAlign[!] [FIELD#] DELIMITER_KEY [OPTIONS] " Using arbitrary regular expressions - :EasyAlign [FIELD#] /REGEXP/ [OPTIONS] + :EasyAlign[!] [FIELD#] /REGEXP/ [OPTIONS] For example, when aligning the following lines around colons and semi-colons, @@ -93,7 +92,8 @@ try these commands: - :EasyAlign **/[:;]\+/ Notice that you can't append `\zs` to your regular expression to put delimiters -on the left. It can be done by providing additional options. +on the left. It can be done by providing additional options in Vim dictionary +format. - :EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': '' } @@ -110,7 +110,7 @@ You can even omit spaces between the arguments, so concisely (or cryptically): - :EasyAlign*/[:;]\+/{'s':1,'l':''} -Available options for each alignment are as follows. +Available options are as follows. | Atrribute | Type | Default | | ---------------- | ---------------- | ----------------------- | @@ -164,11 +164,16 @@ becomes as follows on `:` Naturally, this feature only works when syntax highlighting is enabled. -You can change the default rule by defining `g:easy_align_ignores` array. +You can change the default rule by either defining global `g:easy_align_ignores` +array, " Ignore nothing! let g:easy_align_ignores = [] +or providing `ignores` option directly to :EasyAlign command + + :EasyAlign:{'is':[]} + Then you get, { @@ -181,7 +186,7 @@ Then you get, } -Handling unmatched lines *g:easy_align_ignore_unmatched* +Ignoring unmatched lines *g:easy_align_ignore_unmatched* ------------------------------------------------------------------------- Lines without any matching delimiter are ignored as well (except in @@ -209,8 +214,16 @@ this is usually what we want. However, this default behavior is also configurable. +One way is to set the global `g:easy_align_ignore_unmatched` variable to 0. + let g:easy_align_ignore_unmatched = 0 +Or in non-interactive mode, you can provide `ignore_unmatched` option to +`:EasyAlign` command as follows. + + :EasyAlign:{'iu':0} + + Then we get, { @@ -225,10 +238,14 @@ Then we get, Extending alignment rules *g:easy_align_delimiters* ------------------------------------------------------------------------- +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`. + let g:easy_align_delimiters = { \ '>': { 'pattern': '>>\|=>\|>' }, - \ '/': { 'pattern': '//\+' }, - \ '#': { 'pattern': '#\+' }, + \ '/': { 'pattern': '//\+\|/\*\|\*/', 'ignores': ['String'] }, + \ '#': { 'pattern': '#\+', 'ignores': ['String'] }, \ ']': { \ 'pattern': '[\[\]]', \ 'left_margin': 0,