diff --git a/EXAMPLES.md b/EXAMPLES.md index 399965e..9f438e7 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -1,18 +1,23 @@ -vim-easy-align examples -======================= +easy-align examples +=================== Open this document in your Vim and try it yourself. -This document assumes that you have defined the following mappings. +This document assumes that you have the following mappings in your .vimrc. ```vim -" Start interactive EasyAlign in visual mode (e.g. vip) -vmap (EasyAlign) +" Start interactive EasyAlign in visual mode (e.g. vipga) +xmap ga (EasyAlign) -" Start interactive EasyAlign for a motion/text object (e.g. aip) -nmap a (EasyAlign) +" Start interactive EasyAlign for a motion/text object (e.g. gaip) +nmap ga (EasyAlign) ``` +You can use either of the maps. Place the cursor on the paragraph and press + +- `gaip` "(ga) start easy-align on (i)nner (p)aragraph" +- or `vipga` "(v)isual-select (i)nner (p)aragraph and (ga) start easy-align" + To enable syntax highlighting in the code blocks, define and call the following function. @@ -37,15 +42,17 @@ Alignment around whitespaces You can align text around whitespaces with `` delimiter key. -Try these commands: +Start the interactive mode as described above (`gaip` or `vipga`) and try +these commands: + +- `` +- `2` +- `*` +- `-` +- `-2` - `` -- `2` - `*` -- `-` -- `-2` -- `` - `*` -- `*` ### Example @@ -61,12 +68,13 @@ Pete Best 1941 Formatting table ---------------- -Try these commands: +Again, start the interactive mode and try these commands: + +- `*|` +- `**|` - `*|` - `**|` - `*|` -- `**|` -- `*|` ### Example @@ -88,15 +96,16 @@ Try these commands: Alignment around = ------------------ -The default rule for delimiter key `=` aligns around a whole family of operators -containing `=` character. +The default rule for delimiter key `=` aligns around a whole family of +operators containing `=` character. -Try these commands: -- `=` -- `*=` +Try these commands in the interactive mode. + +- `=` +- `*=` +- `**=` - `**=` -- `**=` -- `*=` +- `*=` ### Example @@ -132,8 +141,8 @@ gg <=> ee Formatting YAML (or JSON) ------------------------- -Try `:` here, to align text around only the first occurrences of colons. -In this case, you don't want to align around all the colons: `*:`. +You can use `:`-rule here to align text around only the first occurrences of +colons. In this case, you don't want to align around all the colons: `*:`. ```yaml mysql: @@ -148,7 +157,7 @@ mysql: Formatting multi-line method chaining ------------------------------------- -Try `.` or `*.` on the following lines. +Try `.` or `*.` on the following lines. ```ruby my_object @@ -174,8 +183,8 @@ Using blockwise-visual mode or negative N-th parameter ------------------------------------------------------ You can try either: -- select text around `=>` in blockwise-visual mode (`CTRL-V`) and `=` -- or `-=` +- select text around `=>` in blockwise-visual mode (`CTRL-V`) and `ga=` +- or `gaip-=` ```ruby options = { :caching => nil, @@ -186,8 +195,7 @@ options = { :caching => nil, Commas ------ -There is also a predefined rule for commas, try `*,` on the following -lines. +There is also a predefined rule for commas, try `*,`. ``` aaa, bb,c @@ -201,7 +209,7 @@ Ignoring delimiters in comments or strings ------------------------------------------ Delimiters highlighted as comments or strings are ignored by default, try -`*=` on the following lines. +`gaip*=` on the following lines. ```c @@ -226,9 +234,9 @@ apple = 1 # comment not aligned banana = 'Gros Michel' # comment 2 ``` -So, how do we align the trailing comments in the above lines? -Simply try `-`. The spaces in the comments are ignored, so the -trailing comment in each line is considered to be a single chunk. +So, how do we align the trailing comments in the above lines? Simply try +`-`. The spaces in the comments are ignored, so the trailing comment in +each line is considered to be a single chunk. But that doesn't work in the following case. @@ -253,7 +261,7 @@ let g:easy_align_delimiters['#'] = { 'pattern': '#', 'ignore_groups': ['String'] Notice that the rule overrides `ignore_groups` attribute in order *not to ignore* delimiters highlighted as comments. -Then on `#`, we get +Then on `#`, we get ```ruby apple = 1 # comment not aligned @@ -266,13 +274,16 @@ command: ```vim " Using regular expression /#/ -" - "is" is fuzzy-matched to "*i*gnore*s*" -:EasyAlign/#/{'is':['String']} +" - "ig" is a shorthand notation of "ignore_groups" +:EasyAlign/#/{'ig':['String']} + +" Or more concisely with the shorthand notation; +:EasyAlign/#/ig['String'] ``` -In this case, the second line is ignored as it doesn't contain a `#`. (The one -highlighted as String is ignored.) If you don't want the second line to be -ignored, there are three options: +In this case, the second line is ignored as it doesn't contain a `#` (The one +in `'F#AD'` is ignored as it's highlighted as String). If you don't want the +second line to be ignored, there are three options: 1. Set global `g:easy_align_ignore_unmatched` flag to 0 2. Use `:EasyAlign` command with `ignore_unmatched` option @@ -284,11 +295,13 @@ let g:easy_align_ignore_unmatched = 0 " 2. Using :EasyAlign command with ignore_unmatched option " 2-1. Using predefined rule with delimiter key # -" - "iu" is fuzzy-matched to "*i*gnore_*u*nmatched" +" - "iu" is expanded to "*i*gnore_*u*nmatched" :EasyAlign#{'iu':0} +" or +:EasyAlign#iu0 " 2-2. Using regular expression /#/ -:EasyAlign/#/{'is':['String'],'iu':0} +:EasyAlign/#/ig['String']iu0 " 3. Update the alignment rule with ignore_unmatched option let g:easy_align_delimiters['#'] = { @@ -315,7 +328,7 @@ static double pi = 3.14; ``` We can align these lines with the predefined `=` rule. Select the lines and -press `=` +press `ga=` ```c const char* str = "Hello"; @@ -325,7 +338,7 @@ static double pi = 3.14; Not bad. However, the names of the variables, `str`, `count`, and `pi` are not aligned with each other. Can we do better? We can clearly see that simple -`` won't properly align those names. +``-rule won't properly align those names. So let's define an alignment rule than can handle this case. ```vim @@ -336,7 +349,7 @@ let g:easy_align_delimiters['d'] = { ``` This new rule aligns text around spaces that are *not* preceded by -`const` or `static`. Let's try it with `d`. +`const` or `static`. Let's select the lines and try `gad`. ```c const char* str = "Hello"; @@ -345,7 +358,7 @@ static double pi = 3.14; ``` Okay, the names are now aligned. We select the lines again with `gv`, and then -press `=` to finish our alignment. +press `ga=` to finish our alignment. ```c const char* str = "Hello"; @@ -376,14 +389,14 @@ So what do we do? Let's try to improve our alignment rule. ```vim let g:easy_align_delimiters['d'] = { -\ 'pattern': ' \(\S\+\s*[;=]\)\@=', +\ 'pattern': ' \ze\S\+\s*[;=]', \ 'left_margin': 0, 'right_margin': 0 \ } ``` Now the new rule has changed to align text around spaces that are followed by some non-whitespace characters and then an equals sign or a semi-colon. -Try `d` +Try `vipgad` ```c const char* str = "Hello"; @@ -392,7 +405,7 @@ static double pi = 3.14; static std::map* scores = pointer; ``` -We're right on track, now press `gv=` and voila! +We're right on track, now press `gvga=` and voila! ```c const char* str = "Hello";