Update documentation

e.g. :EasyAlign=l2r2dlmlr**

.gitattributes

@@ -1,5 +1,6 @@
 .gitattributes export-ignore
 .gitignore     export-ignore
 doc/tags       export-ignore
-README.md      export-ignore
+*.md           export-ignore
 zip            export-ignore
+test/*         export-ignore

DEMO.md

@@ -0,0 +1,91 @@
+# vim: set buftype=nofile colorcolumn= scrolloff=0 noshowcmd:
+
+vim-easy-align
+==============
+
+Where's Lennon?
+---------------
+
+Paul McCartney 1942
+George Harrison 1943
+Ringo Starr 1940
+Pete Best 1941
+
+
+Formatting table
+----------------
+```
+
+| Option| Type | Default | Description |
+|--|--|--|--|
+| threads | Fixnum | 1 | number of threads in the thread pool |
+|queues |Fixnum | 1 | number of concurrent queues |
+|queue_size | Fixnum | 1000 | size of each queue |
+|   interval | Numeric | 0 | dispatcher interval for processing |
+|batch | Boolean | false | enables batch processing mode |
+ |batch_size | Fixnum | nil | maximum number of items in batch|
+ |logger | Logger | nil | logger instance for debug logs |
+
+```
+Operators with = sign
+---------------------
+```ruby
+
+a =
+a = 1
+bbbb = 2
+ccccccc = 3
+ccccccccccccccc
+ddd = 4
+eeee === eee = eee = eee=f
+fff = ggg += gg &&= gg
+g != hhhhhhhh == 888
+i   := 5
+i     %= 5
+i       *= 5
+j     =~ 5
+j   >= 5
+aa      =>         123
+aa <<= 123
+aa        >>= 123
+bbb               => 123
+c     => 1233123
+d   =>      123
+dddddd &&= 123
+dddddd ||= 123
+dddddd /= 123
+gg <=> ee
+
+```
+Formatting YAML (or JSON)
+-------------------------
+```yaml
+
+mysql:
+  # JDBC driver for MySQL database:
+  driver: com.mysql.jdbc.Driver
+  # JDBC URL for the connection (jdbc:mysql://HOSTNAME/DATABASE)
+  url: jdbc:mysql://localhost/test
+  database: test
+  "user:pass":r00t:pa55
+
+```
+Using blockwise-visual mode or negative N-th parameter
+------------------------------------------------------
+```ruby
+
+options = { :caching => nil,
+            :versions => 3,
+            "cache=blocks" => false }.merge(options)
+
+```
+Commas
+------
+
+aaa,   bb,c
+d,eeeeeee
+fffff, gggggggggg,
+h, ,           ii
+j,,k
+
+

EXAMPLES.md

@@ -0,0 +1,396 @@
+vim-easy-align examples
+=======================
+
+Open this document in your Vim and try it yourself.
+
+This document assumes that you have defined the following mapping.
+
+```vim
+vnoremap <silent> <Enter> :EasyAlign<cr>
+```
+
+To enable syntax highlighting in the code blocks, define and call the following
+function.
+
+```vim
+function! GFM()
+  let langs = ['ruby', 'yaml', 'vim', 'c']
+
+  for lang in langs
+    unlet b:current_syntax
+    silent! exec printf("syntax include @%s syntax/%s.vim", lang, lang)
+    exec printf("syntax region %sSnip matchgroup=Snip start='```%s' end='```' contains=@%s",
+                \ lang, lang, lang)
+  endfor
+  let b:current_syntax='mkd'
+
+  syntax sync fromstart
+endfunction
+```
+
+Alignment around whitespaces
+----------------------------
+
+You can align text around whitespaces with `<space>` delimiter key.
+
+Try these commands:
+- `<Enter><space>`
+- `<Enter>2<space>`
+- `<Enter>*<space>`
+- `<Enter>-<space>`
+- `<Enter>-2<space>`
+- `<Enter><Enter><space>`
+- `<Enter><Enter>*<space>`
+- `<Enter><Enter><Enter>*<space>`
+
+### Example
+
+```
+
+Paul McCartney 1942
+George Harrison 1943
+Ringo Starr 1940
+Pete Best 1941
+
+```
+
+Formatting table
+----------------
+
+Try these commands:
+- `<Enter>*|`
+- `<Enter>**|`
+- `<Enter><Enter>*|`
+- `<Enter><Enter>**|`
+- `<Enter><Enter><Enter>*|`
+
+### Example
+
+```
+
+| Option| Type | Default | Description |
+|--|--|--|--|
+| threads | Fixnum | 1 | number of threads in the thread pool |
+|queues |Fixnum | 1 | number of concurrent queues |
+|queue_size | Fixnum | 1000 | size of each queue |
+|   interval | Numeric | 0 | dispatcher interval for batch processing |
+|batch | Boolean | false | enables batch processing mode |
+ |batch_size | Fixnum | nil | number of maximum items to be assigned at once |
+ |logger | Logger | nil | logger instance for debug logs |
+
+```
+
+
+Alignment around =
+------------------
+
+The default rule for delimiter key `=` aligns around a whole family of operators
+containing `=` character.
+
+Try these commands:
+- `<Enter>=`
+- `<Enter>*=`
+- `<Enter>**=`
+- `<Enter><Enter>**=`
+- `<Enter><Enter><Enter>*=`
+
+### Example
+
+```ruby
+
+a =
+a = 1
+bbbb = 2
+ccccccc = 3
+ccccccccccccccc
+ddd = 4
+eeee === eee = eee = eee=f
+fff = ggg += gg &&= gg
+g != hhhhhhhh == 888
+i   := 5
+i     %= 5
+i       *= 5
+j     =~ 5
+j   >= 5
+aa      =>         123
+aa <<= 123
+aa        >>= 123
+bbb               => 123
+c     => 1233123
+d   =>      123
+dddddd &&= 123
+dddddd ||= 123
+dddddd /= 123
+gg <=> ee
+
+```
+
+Formatting YAML (or JSON)
+-------------------------
+
+Try `<Enter>:` here, to align text around only the first occurrences of colons.
+In this case, you don't want to align around all the colons: `<Enter>*:`.
+
+```yaml
+mysql:
+  # JDBC driver for MySQL database:
+  driver: com.mysql.jdbc.Driver
+  # JDBC URL for the connection (jdbc:mysql://HOSTNAME/DATABASE)
+  url: jdbc:mysql://localhost/test
+  database: test
+  "user:pass":r00t:pa55
+```
+
+Formatting multi-line method chaining
+-------------------------------------
+
+Try `<Enter>.` or `<Enter>*.` on the following lines.
+
+```ruby
+my_object
+      .method1().chain()
+    .second_method().call()
+      .third().call()
+     .method_4().execute()
+```
+
+Notice that the indentation is adjusted to match the shortest one among those of
+the lines starting with the delimiter.
+
+```ruby
+my_object
+    .method1()      .chain()
+    .second_method().call()
+    .third()        .call()
+    .method_4()     .execute()
+```
+
+
+Using blockwise-visual mode or negative N-th parameter
+------------------------------------------------------
+
+You can try either:
+- select text around `=>` in blockwise-visual mode (`CTRL-V`) and `<Enter>=`
+- or `<Enter>-=`
+
+```ruby
+options = { :caching => nil,
+            :versions => 3,
+            "cache=blocks" => false }.merge(options)
+```
+
+Commas
+------
+
+There is also a predefined rule for commas, try `<Enter>*,` on the following
+lines.
+
+```
+aaa,   bb,c
+d,eeeeeee
+fffff, gggggggggg,
+h, ,           ii
+j,,k
+```
+
+Ignoring delimiters in comments or strings
+------------------------------------------
+
+Delimiters highlighted as comments or strings are ignored by default, try
+`<Enter>*=` on the following lines.
+
+```c
+
+/* a */ b = c
+aa >= bb
+// aaa = bbb = cccc
+/* aaaa = */ bbbb   === cccc   " = dddd = " = eeee
+aaaaa /* bbbbb */      == ccccc /* != eeeee = */ === fffff
+
+```
+
+This only works when syntax highlighting is enabled.
+
+Aligning in-line comments
+-------------------------
+
+```ruby
+apple = 1 # comment not aligned
+banana = 'Gros Michel' # comment 2
+```
+
+So, how do we align the trailing comments in the above lines?
+Simply try `<Enter>-<space>`. 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.
+
+```ruby
+apple = 1 # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'Gros Michel' # comment 2
+```
+
+That is because the second line doesn't have trailing comment, and
+the last (`-`) space for that line is the one just before `'F#AD'`.
+
+So, let's define a custom mapping for `#`.
+
+```vim
+if !exists('g:easy_align_delimiters')
+  let g:easy_align_delimiters = {}
+endif
+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 `<Enter>#`, we get
+
+```ruby
+apple = 1         # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'string' # comment 2
+```
+
+If you don't want to define the rule, you can do the same with the following
+command:
+
+```vim
+" Using regular expression /#/
+" - "is" is fuzzy-matched to "*i*gnore*s*"
+:EasyAlign/#/{'is':['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:
+
+1. Set global `g:easy_align_ignore_unmatched` flag to 0
+2. Use `:EasyAlign` command with `ignore_unmatched` option
+3. Update the alignment rule with `ignore_unmatched` option
+
+```vim
+" 1. Set global g:easy_align_ignore_unmatched to zero
+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"
+:EasyAlign#{'iu':0}
+
+" 2-2. Using regular expression /#/
+:EasyAlign/#/{'is':['String'],'iu':0}
+
+" 3. Update the alignment rule with ignore_unmatched option
+let g:easy_align_delimiters['#'] = {
+  \ 'pattern': '#', 'ignore_groups': ['String'], 'ignore_unmatched': 0 }
+```
+
+Then we get,
+
+```ruby
+apple = 1                # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'string'        # comment 2
+```
+
+Aligning C-style variable definition
+------------------------------------
+
+Take the following example:
+
+```c
+const char* str = "Hello";
+int64_t count = 1 + 2;
+static double pi = 3.14;
+```
+
+We can align these lines with the predefined `=` rule. Select the lines and
+press `<Enter>=`
+
+```c
+const char* str  = "Hello";
+int64_t count    = 1 + 2;
+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
+`<Enter><space>` won't properly align those names.
+So let's define an alignment rule than can handle this case.
+
+```vim
+let g:easy_align_delimiters['d'] = {
+\ 'pattern': '\(const\|static\)\@<! ',
+\ 'left_margin': 0, 'right_margin': 0
+\ }
+```
+
+This new rule aligns text around spaces that are *not* preceded by
+`const` or `static`. Let's try it with `<Enter>d`.
+
+```c
+const char*   str = "Hello";
+int64_t       count = 1 + 2;
+static double pi = 3.14;
+```
+
+Okay, the names are now aligned. We select the lines again with `gv`, and then
+press `<Enter>=` to finish our alignment.
+
+```c
+const char*   str   = "Hello";
+int64_t       count = 1 + 2;
+static double pi    = 3.14;
+```
+
+So far, so good. However, this rule is not sufficient to handle more complex
+cases involving C++ templates or Java generics. Take the following example:
+
+```c
+const char* str = "Hello";
+int64_t count = 1 + 2;
+static double pi = 3.14;
+static std::map<std::string, float>*    scores = pointer;
+```
+
+We see that our rule above doesn't work anymore.
+
+```c
+const char*                  str = "Hello";
+int64_t                      count = 1 + 2;
+static double                pi = 3.14;
+static std::map<std::string, float>*    scores = pointer;
+```
+
+So what do we do? Let's try to improve our alignment rule.
+
+```vim
+let g:easy_align_delimiters['d'] = {
+\ 'pattern': ' \(\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 `<Enter>d`
+
+```c
+const char*                          str = "Hello";
+int64_t                              count = 1 + 2;
+static double                        pi = 3.14;
+static std::map<std::string, float>* scores = pointer;
+```
+
+We're right on track, now press `gv<Enter>=` and voila!
+
+```c
+const char*                          str    = "Hello";
+int64_t                              count  = 1 + 2;
+static double                        pi     = 3.14;
+static std::map<std::string, float>* scores = pointer;
+```
+

README.md

@@ -1,78 +1,259 @@
 vim-easy-align
 ==============
 
-A simple, easy-to-use Vim alignment plugin without too much ambition.
+A simple, easy-to-use Vim alignment plugin.
 
 Demo
 ----
 
 ![Screencast](https://raw.github.com/junegunn/vim-easy-align/gif/vim-easy-align.gif)
 
-[Screencast](https://vimeo.com/63506219)
+(Too fast? Slower GIF is [here](https://raw.github.com/junegunn/vim-easy-align/gif/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
+
+### _"I already have a similar one. Should I switch?"_
+
+Maybe or maybe not. See [related work](https://github.com/junegunn/vim-easy-align#related-work) section.
 
 Installation
 ------------
 
 Either [download zip file](http://www.vim.org/scripts/script.php?script_id=4520)
-and extract in ~/.vim or use [Vundle](https://github.com/gmarik/vundle) (recommended)
-or [Pathogen](https://github.com/tpope/vim-pathogen).
+and extract in ~/.vim or
+[use](https://github.com/tpope/vim-pathogen)
+[your](https://github.com/gmarik/vundle)
+[favorite](https://github.com/junegunn/vim-plug)
+[plugin](https://github.com/Shougo/neobundle.vim)
+[manager](https://github.com/MarcWeber/vim-addon-manager).
 
-### With Vundle
-
-```vim
-Bundle 'junegunn/vim-easy-align'
-```
+- [Pathogen](https://github.com/tpope/vim-pathogen)
+  - `git clone https://github.com/junegunn/vim-easy-align.git ~/.vim/bundle/vim-easy-align`
+- [Vundle](https://github.com/gmarik/vundle)
+  1. Add `Bundle 'junegunn/vim-easy-align'` to .vimrc
+  2. Run `:BundleInstall`
+- [NeoBundle](https://github.com/Shougo/neobundle.vim)
+  1. Add `NeoBundle 'junegunn/vim-easy-align'` to .vimrc
+  2. Run `:NeoBundleInstall`
+- [vim-plug](https://github.com/junegunn/vim-plug)
+  1. Add `Plug 'junegunn/vim-easy-align'` to .vimrc
+  2. Run `:PlugInstall`
 
 Usage
 -----
 
-_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`.
+_vim-easy-align_ defines `:EasyAlign` command (and the right-align
+variant `:EasyAlign!`) for visual mode.
+
+| Mode                      | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Interactive mode          | `:EasyAlign[!] [OPTIONS]`                        |
+| Using predefined rules    | `:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]`   |
+| Using regular expressions | `:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]`        |
+
+### 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.
+
+### 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`.
 
 ```vim
-vnoremap <silent> <Enter> :EasyAlign<cr>
+vnoremap <silent> <Enter> :EasyAlign<Enter>
 ```
 
-With the mapping, you can align selected lines with a few keystrokes.
+(Of course you can use any key combination as the trigger. e.g. `<Leader>a`)
+
+With the mapping, you can align selected lines of text with only a few keystrokes.
 
 1. `<Enter>` key to start interactive EasyAlign command
-1. Optional Enter keys to toggle right-justification mode
-1. Optional field number (default: 1)
-    - `1`        Alignment around 1st delimiters
-    - `2`        Alignment around 2nd delimiters
+1. Optional: Enter keys to select alignment mode (left, right, or center)
+1. Optional: N-th delimiter (default: 1)
+    - `1`         Around the 1st occurrences of delimiters
+    - `2`         Around the 2nd occurrences of delimiters
     - ...
-    - `*`        Alignment around all delimiters (recursive)
-1. Delimiter (`<space>`, `=`, `:`, `.`, `|`, `,`)
+    - `*`         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
+    - ...
+1. Delimiter key (a single keystroke; `<space>`, `=`, `:`, `.`, `|`, `,`)
 
-Alignment rules for the following delimiters have been crafted to meet the most needs.
+Alignment rules for the following delimiters have been defined to meet the most needs.
 
-| Delimiter | Description/Use cases                                      |
-| --------- | ---------------------------------------------------------- |
-| `<space>` | General alignment around spaces                            |
-| `=`       | Operators containing equals sign (=, ==, !=, +=, &&=, ...) |
-| `:`       | Suitable for formatting JSON or YAML                       |
-| `.`       | Multi-line method chaining                                 |
-| `,`       | Multi-line method arguments                                |
-| &#124;    | Table markdown                                             |
+| Delimiter key | Description/Use cases                                                |
+| ------------- | -------------------------------------------------------------------- |
+| `<space>`     | General alignment around whitespaces                                 |
+| `=`           | Operators containing equals sign (`=`, `==,` `!=`, `+=`, `&&=`, ...) |
+| `:`           | Suitable for formatting JSON or YAML                                 |
+| `.`           | Multi-line method chaining                                           |
+| `,`           | Multi-line method arguments                                          |
+| &#124;        | Table markdown                                                       |
 
-### Example command sequences
+You can override these default rules or define your own rules with
+`g:easy_align_delimiters`, which will be described in
+[the later section](https://github.com/junegunn/vim-easy-align#extending-alignment-rules).
 
-| With visual map   | Description                                       | Equivalent command      |
-| ----------------- | ------------------------------------------------- | ----------------------- |
-| `<Enter>=`        | Alignment around 1st equals signs (and the likes) | `:'<,'>EasyAlign=`      |
-| `<Enter>2=`       | Alignment around 2nd equals signs (and the likes) | `:'<,'>EasyAlign2=`     |
-| `<Enter>3=`       | Alignment around 3rd equals signs (and the likes) | `:'<,'>EasyAlign3=`     |
-| `<Enter>*=`       | Alignment around all equals signs (and the likes) | `:'<,'>EasyAlign*=`     |
-| `<Enter><Enter>=` | Right-justified alignment around 1st equals signs | `:'<,'>EasyAlignRight=` |
-| `<Enter><space>`  | Alignment around 1st space                        | `:'<,'>EasyAlign\ `     |
-| `<Enter>2<space>` | Alignment around 2nd space                        | `:'<,'>EasyAlign2\ `    |
-| `<Enter>:`        | Alignment around 1st colon                        | `:'<,'>EasyAlign:`      |
-| ...               | ...                                               |                         |
+#### Example command sequences
+
+| With visual map     | Description                                             | Equivalent command     |
+| ------------------- | ------------------------------------------------------- | ---------------------- |
+| `<Enter><space>`    | Alignment around 1st whitespaces                        | `:'<,'>EasyAlign\ `    |
+| `<Enter>2<space>`   | Alignment around 2nd whitespaces                        | `:'<,'>EasyAlign2\ `   |
+| `<Enter>-<space>`   | Alignment around the last whitespaces                   | `:'<,'>EasyAlign-\ `   |
+| `<Enter>-2<space>`  | Alignment around the 2nd to last whitespaces            | `:'<,'>EasyAlign-2\ `  |
+| `<Enter>:`          | Alignment around 1st colon (`key:  value`)              | `:'<,'>EasyAlign:`     |
+| `<Enter><Right>:`   | Alignment around 1st colon (`key : value`)              | `:'<,'>EasyAlign:s0l1` |
+| `<Enter>=`          | Alignment around 1st operators with =                   | `:'<,'>EasyAlign=`     |
+| `<Enter>2=`         | Alignment around 2nd operators with =                   | `:'<,'>EasyAlign2=`    |
+| `<Enter>3=`         | Alignment around 3rd operators with =                   | `:'<,'>EasyAlign3=`    |
+| `<Enter>*=`         | Alignment around all operators with =                   | `:'<,'>EasyAlign*=`    |
+| `<Enter>**=`        | Left-right alternating alignment around all = operators | `:'<,'>EasyAlign**=`   |
+| `<Enter><Enter>=`   | Right alignment around 1st equals signs                 | `:'<,'>EasyAlign!=`    |
+| `<Enter><Enter>**=` | Right-left alternating alignment around all = operators | `:'<,'>EasyAlign!**=`  |
+
+#### Using regular expressions
+
+Instead of finishing the command with a predefined delimiter key, you can type
+in a regular expression after `<CTRL-/>` or `<CTRL-X>` key.
+For example, if you want to align text around all occurrences of numbers:
+
+- `<Enter>`
+- `*`
+- `<CTRL-/>` (or `<CTRL-X>` on GVim)
+  - `[0-9]\+`
+
+#### Alignment options in interactive mode
+
+While in interactive mode, you can set alignment options using special shortcut
+keys listed below. The meaning of each option will be described in
+[the following sections](https://github.com/junegunn/vim-easy-align#alignment-options).
+
+| Key       | Option             | Values                                             |
+| --------  | ------------------ | -------------------------------------------------- |
+| `CTRL-I`  | `indentation`      | shallow, deep, none, keep                          |
+| `CTRL-L`  | `left_margin`      | Input number or string                             |
+| `CTRL-R`  | `right_margin`     | Input number or string                             |
+| `CTRL-D`  | `delimiter_align`  | left, center, right                                |
+| `CTRL-U`  | `ignore_unmatched` | 0, 1                                               |
+| `CTRL-G`  | `ignore_groups`    | [], ['String'], ['Comment'], ['String', 'Comment'] |
+| `CTRL-O`  | `mode_sequence`    | Input string of `/[lrc]+\*{0,2}/`                  |
+| `<Left>`  | `stick_to_left`    | `{ 'stick_to_left': 1, 'left_margin': 0 }`         |
+| `<Right>` | `stick_to_left`    | `{ 'stick_to_left': 0, 'left_margin': 1 }`         |
+| `<Down>`  | `*_margin`         | `{ 'left_margin': 0, 'right_margin': 0 }`          |
+
+After a successful alignment, you can repeat the same operation using the
+repeatable, non-interactive command recorded in `g:easy_align_last_command`.
+
+```vim
+:<C-R>=g:easy_align_last_command<Enter><Enter>
+```
+
+---
+
+### *Intermission*
+
+You can stop reading here. Trust me. All the fancy features described in the
+following sections are really powerful but you won't be needing them in most
+of the cases.
+
+Go try out vim-easy-align right now, and come back later when you feel like it.
+
+---
+
+### Using `EasyAlign` in command line
+
+Instead of going into the interactive mode, you can just type in arguments to
+`:EasyAlign` command.
+
+```vim
+" Using predefined alignment rules
+:EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]
+
+" Using arbitrary regular expressions
+:EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]
+```
+
+For example, when aligning the following lines around colons and semi-colons,
+
+    apple;:banana::cake
+    data;;exchange:;format
+
+try these commands:
+
+- `:EasyAlign /[:;]\+/`
+- `:EasyAlign 2/[:;]\+/`
+- `:EasyAlign */[:;]\+/`
+- `: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 in Vim dictionary
+format.
+
+- `:EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }`
+
+Then we get:
+
+    apple;: banana::   cake
+    data;;  exchange:; format
+
+Option names are fuzzy-matched, so you can write as follows:
+
+- `:EasyAlign * /[:;]\+/ { 'stl': 1, 'l': 0 }`
+
+You can even omit spaces between the arguments, so concisely (or cryptically):
+
+- `:EasyAlign*/[:;]\+/{'s':1,'l':0}`
+
+Nice. But let's make it even shorter. Option values can be written in shorthand
+notation.
+
+- `:EasyAlign*/[:;]\+/s1l0`
+
+The following table summarizes the shorthand notation.
+
+| Option           | Expression |
+| ---------------- | ---------- |
+| left_margin      | `l[0-9]+`  |
+| right_margin     | `r[0-9]+`  |
+| stick_to_left    | `s[01]`    |
+| ignore_unmatched | `iu[01]`   |
+| ignore_groups    | `ig\[.*\]` |
+| delimiter_align  | `d[lrc]`   |
+| mode_sequence    | `m[lrc*]*` |
+| indentation      | `i[ksdn]`  |
+
+For your information, the same thing can be done in the interactive mode as well
+with the following key combination.
+
+- `<Enter>`
+- `*`
+- `<Left>`
+- `<CTRL-/>` (or `<CTRL-X>` on GVim)
+  - `[:;]\+`
 
 ### Partial alignment in blockwise-visual mode
 
 In blockwise-visual mode (`CTRL-V`), EasyAlign command aligns only the selected
-parts, instead of the whole lines in the range.
+text in the block, instead of the whole lines in the range.
 
 Consider the following case where you want to align text around `=>` operators.
 
@@ -82,9 +263,9 @@ my_hash = { :a => 1,
             :aaa => 3 }
 ```
 
-In non-blockwise visual mode (`v` / `V`), `<Enter>=` won't work since the assignment
-operator in the first line gets in the way.
-So we instead enter blockwise-visual mode (`CTRL-V`), and select the text *around*
+In non-blockwise visual mode (`v` / `V`), `<Enter>=` won't work since the
+assignment operator in the first line gets in the way. So we instead enter
+blockwise-visual mode (`CTRL-V`), and select the text *around*
 `=>` operators, then press `<Enter>=`.
 
 ```ruby
@@ -93,75 +274,434 @@ my_hash = { :a   => 1,
             :aaa => 3 }
 ```
 
-Defining custom alignment rules
--------------------------------
+However, in this case, we don't really need blockwise visual mode
+since the same can be easily done using the negative N-th parameter: `<Enter>-=`
+
+Alignment options
+-----------------
+
+### List of options
+
+| Option             | Type    | Default               | Description                                             |
+| ------------------ | ------- | --------------------- | ------------------------------------------------------- |
+| `left_margin`      | number  | 1                     | Number of spaces to attach before delimiter             |
+| `left_margin`      | string  | `' '`                 | String to attach before delimiter                       |
+| `right_margin`     | number  | 1                     | Number of spaces to attach after delimiter              |
+| `right_margin`     | string  | `' '`                 | String to attach after delimiter                        |
+| `stick_to_left`    | boolean | 0                     | Whether to position delimiter on the left-side          |
+| `ignore_groups`    | list    | ['String', 'Comment'] | Delimiters in these syntax highlight groups are ignored |
+| `ignore_unmatched` | boolean | 1                     | Whether to ignore lines without matching delimiter      |
+| `indentation`      | string  | `k`                   | Indentation method (*k*eep, *d*eep, *s*hallow, *n*one)  |
+| `delimiter_align`  | string  | `r`                   | Determines how to align delimiters of different lengths |
+| `mode_sequence`    | string  |                       | Alignment modes for multiple occurrences of delimiters  |
+
+There are 4 ways to set alignment options (from lowest precedence to highest):
+
+1. Some option values can be set with corresponding global variables
+2. Option values can be specified in the definition of each alignment rule
+3. Option values can be given as arguments to `:EasyAlign` command
+4. Option values can be set in interactive mode using special shortcut keys
+
+| Option name        | Shortcut key        | Abbreviated | Global variable                 |
+| ------------------ | ------------------- | ----------- | ------------------------------- |
+| `left_margin`      | `CTRL-L`            | `l[0-9]+`   |                                 |
+| `right_margin`     | `CTRL-R`            | `r[0-9]+`   |                                 |
+| `stick_to_left`    | `<Left>`, `<Right>` | `s[01]`     |                                 |
+| `ignore_groups`    | `CTRL-G`            | `ig\[.*\]`  | `g:easy_align_ignore_groups`    |
+| `ignore_unmatched` | `CTRL-U`            | `iu[01]`    | `g:easy_align_ignore_unmatched` |
+| `indentation`      | `CTRL-I`            | `i[ksdn]`   | `g:easy_align_indentation`      |
+| `delimiter_align`  | `CTRL-D`            | `d[lrc]`    | `g:easy_align_delimiter_align`  |
+| `mode_sequence`    | `CTRL-O`            | `m[lrc*]*`  |                                 |
+
+### Ignoring delimiters in comments or strings
+
+EasyAlign can be configured to ignore delimiters in certain syntax highlight
+groups, such as code comments or strings. By default, delimiters that are
+highlighted as code comments or strings are ignored.
+
+```vim
+" Default:
+"   If a delimiter is in a highlight group whose name matches
+"   any of the followings, it will be ignored.
+let g:easy_align_ignore_groups = ['Comment', 'String']
+```
+
+For example, the following paragraph
+
+```ruby
+{
+  # Quantity of apples: 1
+  apple: 1,
+  # Quantity of bananas: 2
+  bananas: 2,
+  # Quantity of grape:fruits: 3
+  'grape:fruits': 3
+}
+```
+
+becomes as follows on `<Enter>:` (or `:EasyAlign:`)
+
+```ruby
+{
+  # Quantity of apples: 1
+  apple:          1,
+  # Quantity of bananas: 2
+  bananas:        2,
+  # Quantity of grape:fruits: 3
+  'grape:fruits': 3
+}
+```
+
+Naturally, this feature only works when syntax highlighting is enabled.
+
+You can change the default rule by using one of these 4 methods.
+
+1. Press `CTRL-G` in interactive mode to switch groups
+2. Define global `g:easy_align_ignore_groups` list
+3. Define a custom rule in `g:easy_align_delimiters` with `ignore_groups` option
+4. Provide `ignore_groups` option to `:EasyAlign` command.
+   e.g. `:EasyAlign:ig[]`
+
+For example if you set `ignore_groups` option to be an empty list, you get
+
+```ruby
+{
+  # Quantity of apples:  1
+  apple:                 1,
+  # Quantity of bananas: 2
+  bananas:               2,
+  # Quantity of grape:   fruits: 3
+  'grape:                fruits': 3
+}
+```
+
+Satisfied? :satisfied:
+
+### Ignoring unmatched lines
+
+`ignore_unmatched` option determines how EasyAlign command processes lines that
+do not have N-th delimiter.
+
+1. In left-alignment mode, they are ignored
+2. In right or center-alignment mode, they are *not* ignored, and the last
+   tokens from those lines are aligned as well as if there is an invisible
+   trailing delimiter at the end of each line
+3. If `ignore_unmatched` is 1, they are ignored regardless of the alignment mode
+4. If `ignore_unmatched` is 0, they are *not* ignored regardless of the mode
+
+Let's take an example.
+When we align the following code block around the (1st) colons,
+
+```ruby
+{
+  apple: proc {
+    this_line_does_not_have_a_colon
+  },
+  bananas: 2,
+  grapefruits: 3
+}
+```
+
+this is usually what we want.
+
+```ruby
+{
+  apple:       proc {
+    this_line_does_not_have_a_colon
+  },
+  bananas:     2,
+  grapefruits: 3
+}
+```
+
+However, we can override this default behavior by setting `ignore_unmatched`
+option to zero using one of the following methods.
+
+1. Press `CTRL-U` in interactive mode to toggle `ignore_unmatched` option
+2. Set the global `g:easy_align_ignore_unmatched` variable to 0
+3. Define a custom alignment rule with `ignore_unmatched` option set to 0
+4. Provide `ignore_unmatched` option to `:EasyAlign` command. e.g. `:EasyAlign:iu0`
+
+Then we get,
+
+```ruby
+{
+  apple:                             proc {
+    this_line_does_not_have_a_colon
+  },
+  bananas:                           2,
+  grapefruits:                       3
+}
+```
+
+### Aligning delimiters of different lengths
+
+Global `g:easy_align_delimiter_align` option and rule-wise/command-wise
+`delimiter_align` option determines how matched delimiters of different lengths
+are aligned.
+
+```ruby
+apple = 1
+banana += apple
+cake ||= banana
+```
+
+By default, delimiters are right-aligned as follows.
+
+```ruby
+apple    = 1
+banana  += apple
+cake   ||= banana
+```
+
+However, with `:EasyAlign=dl`, delimiters are left-aligned.
+
+```ruby
+apple  =   1
+banana +=  apple
+cake   ||= banana
+```
+
+And on `:EasyAlign=dc`, center-aligned.
+
+```ruby
+apple   =  1
+banana +=  apple
+cake   ||= banana
+```
+
+In interactive mode, you can change the option value with `CTRL-D` key.
+
+### Adjusting indentation
+
+By default :EasyAlign command keeps the original indentation of the lines. But
+then again we have `indentation` option. See the following example.
+
+```ruby
+# Lines with different indentation
+  apple = 1
+    banana = 2
+      cake = 3
+        daisy = 4
+     eggplant = 5
+
+# Default: _k_eep the original indentation
+#   :EasyAlign=
+  apple       = 1
+    banana    = 2
+      cake    = 3
+        daisy = 4
+     eggplant = 5
+
+# Use the _s_hallowest indentation among the lines
+#   :EasyAlign=is
+  apple    = 1
+  banana   = 2
+  cake     = 3
+  daisy    = 4
+  eggplant = 5
+
+# Use the _d_eepest indentation among the lines
+#   :EasyAlign=id
+        apple    = 1
+        banana   = 2
+        cake     = 3
+        daisy    = 4
+        eggplant = 5
+
+# Indentation: _n_one
+#   :EasyAlign=in
+apple    = 1
+banana   = 2
+cake     = 3
+daisy    = 4
+eggplant = 5
+```
+
+Notice that `idt` is fuzzy-matched to `indentation`.
+
+In interactive mode, you can change the option value with `CTRL-I` key.
+
+### Alignments over multiple occurrences of delimiters
+
+As stated above, "N-th" parameter is used to target specific occurrences of
+the delimiter when it appears multiple times in each line.
+
+To recap:
+
+```vim
+" Left-alignment around the FIRST occurrences of delimiters
+:EasyAlign =
+
+" Left-alignment around the SECOND occurrences of delimiters
+:EasyAlign 2=
+
+" Left-alignment around the LAST occurrences of delimiters
+:EasyAlign -=
+
+" Left-alignment around ALL occurrences of delimiters
+:EasyAlign *=
+
+" Left-right ALTERNATING alignment around all occurrences of delimiters
+:EasyAlign **=
+
+" Right-left ALTERNATING alignment around all occurrences of delimiters
+:EasyAlign! **=
+```
+
+In addition to these, you can fine-tune alignments over multiple occurrences of
+the delimiters with 'mode_sequence' option. (The option can also be set
+in interactive mode with the special key `CTRL-O`)
+
+```vim
+" Left alignment over the first two occurrences of delimiters
+:EasyAlign = { 'mode_sequence': 'll' }
+
+" Right, left, center alignment over the 1st to 3rd occurrences of delimiters
+:EasyAlign = { 'm': 'rlc' }
+
+" Using shorthand notation
+:EasyAlign = mrlc
+
+" Right, left, center alignment over the 2nd to 4th occurrences of delimiters
+:EasyAlign 2=mrlc
+
+" (*) Repeating alignments (default: l, r, or c)
+"   Right, left, center, center, center, center, ...
+:EasyAlign *=mrlc
+
+" (**) Alternating alignments (default: lr or rl)
+"   Right, left, center, right, left, center, ...
+:EasyAlign **=mrlc
+
+" Right, left, center, center, center, ... repeating alignment
+" over the 3rd to the last occurrences of delimiters
+:EasyAlign 3=mrlc*
+
+" Right, left, center, right, left, center, ... alternating alignment
+" over the 3rd to the last occurrences of delimiters
+:EasyAlign 3=mrlc**
+```
+
+### Extending alignment rules
+
+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`.
+
+#### Example
 
 ```vim
 let g:easy_align_delimiters = {
 \ '>': { 'pattern': '>>\|=>\|>' },
-\ '/': { 'pattern': '//*' },
-\ 'x': {
-\     'pattern':       '[xX]',
-\     'margin_left':   ' <<<',
-\     'margin_right':  '>>> ',
+\ '/': { 'pattern': '//\+\|/\*\|\*/', 'ignore_groups': ['String'] },
+\ '#': { 'pattern': '#\+', 'ignore_groups': ['String'], 'delimiter_align': 'l' },
+\ ']': {
+\     'pattern':       '[[\]]',
+\     'left_margin':   0,
+\     'right_margin':  0,
 \     'stick_to_left': 0
+\   },
+\ ')': {
+\     'pattern':       '[()]',
+\     'left_margin':   0,
+\     'right_margin':  0,
+\     'stick_to_left': 0
+\   },
+\ 'd': {
+\     'pattern': ' \(\S\+\s*[;=]\)\@=',
+\     'left_margin': 0,
+\     'right_margin': 0
 \   }
 \ }
 ```
 
-Handling unmatched lines
-------------------------
+Advanced examples and use cases
+-------------------------------
 
-EasyAlign by default ignores lines without the matching delimiters (except in right-justification mode).
-This is to ignore interleaved comments commonly found in code.
+See [EXAMPLES.md](https://github.com/junegunn/vim-easy-align/blob/master/EXAMPLES.md)
+for more examples.
 
-For example, when aligning the following code block,
 
-```
-{
-  # Quantity of apples
-  apple: 1,
-  # Quantity of bananas
-  bananas: 2,
-  # Quantity of grapefruits
-  grapefruits: 3
-}
+Related work
+------------
+
+There are two well-known plugins with the same goal as that of vim-easy-align.
+
+- [DrChip's Alignment Tool for Vim](http://www.drchip.org/astronaut/vim/align.html) (herein will be referred to as "Align")
+- [Tabular](https://github.com/godlygeek/tabular)
+
+Both are great plugins with very large user bases. I actually had been a Tabular
+user for a couple of years before I finally made up my mind to roll out my own.
+
+So why would someone choose vim-easy-align over those two?
+
+Feature-by-feature comparison I believe is not quite useful, since a typical
+user will end up using only a small subset of the features.
+So I will mention just a few core benefits of vim-easy-align.
+
+### Ease of use
+
+As the name implies, vim-easy-align is *easier* to use. Its interactive mode
+allows you to achieve what you want with just a few keystrokes.
+The key sequence is mnemonic, so it's easy to remember and execute.
+It even feels like a native Vim command!
+
+- *Right-align*: `<Enter><Enter>`
+- around the *second* occurrences: `2`
+- of *whitespaces*: `<space>`
+
+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
+complex regular expressions.
+
+_"How am I going to align the third to the last word in each line to the right
+without affecting the ones before it?"_
+
+### Clean
+
+vim-easy-align doesn't clutter your workspace with mappings and global
+variables. All you would need is a single mapping to the interactive EasyAlign
+command, and even that is totally up to you.
+
+### Optimized for code editing
+
+vim-easy-align by default performs syntax-aware alignment, which is invaluable
+when editing codes.
+
+Try to come up with a regular expression to correctly format the following code
+snippet. With vim-easy-align under default configuration and a mapping, it can
+be done with just two keystrokes: `<Enter>:`
+
+```javascript
+var jdbc = {
+  // JDBC driver for MySQL database:
+  driver: "com.mysql.jdbc.Driver",
+  /* JDBC URL for the connection (jdbc:mysql://HOSTNAME/DATABASE) */
+  url: 'jdbc:mysql://localhost/test',
+  database: "test",
+  "user:pass":"r00t:pa55"
+};
 ```
 
-we don't want the comment lines to affect the alignment,
-so this is usually what we want.
+(To be fair, Align also can be configured to consider syntax highlighting with
+`g:AlignSkip` function reference which should point to a custom function that
+looks up the syntax group of a character on a certain position)
 
-```
-{
-  # Quantity of apples
-  apple:       1,
-  # Quantity of bananas
-  bananas:     2,
-  # Quantity of grapefruits
-  grapefruits: 3
-}
-```
+### "Okay. So should I switch?"
 
-However, this default behavior is configurable.
+Maybe, but I can't really say. I have no ambition to make vim-easy-align
+an absolute superior to the others. For some cases, vim-easy-align works better
+than the others, but for some other cases, Tabular or Align.vim might be a
+better choice.
 
-```vim
-let g:easy_align_ignore_unmatched = 0
-```
-
-Then we get,
-
-```
-{
-  # Quantity of apples
-  apple:                     1,
-  # Quantity of bananas
-  bananas:                   2,
-  # Quantity of grapefruits
-  grapefruits:               3
-}
-```
+So try it yourself and see if it works for you!
 
 Author
 ------
 
 [Junegunn Choi](https://github.com/junegunn)
+
+License
+-------
+
+MIT

doc/easy_align.txt

@@ -1,32 +1,50 @@
+*easy_align.txt*  A simple, easy-to-use Vim alignment plugin
+
 vim-easy-align                              *vim-easy-align* *easy-align*
 =========================================================================
 
-A simple, easy-to-use Vim alignment plugin without too much ambition.
+A simple, easy-to-use Vim alignment plugin.
 
-  Author: Junegunn Choi
-  Source: https://github.com/junegunn/vim-easy-align
+  Author:  Junegunn Choi
+  Source:  https://github.com/junegunn/vim-easy-align
+  License: MIT
 
 
-EasyAlign                                                     *EasyAlign*
+EasyAlign                                      *:EasyAlign* *:EasyAlign!*
 -------------------------------------------------------------------------
 
-vim-easy-align defines interactive `:EasyAlign` command in the visual mode.
+vim-easy-align defines `:EasyAlign` command in the visual mode.
+(:EasyAlign! is the right-align version.)
 
-For convenience, it is advised that you define a mapping for triggering it
-in your `.vimrc`.
+| Mode                      | Command                                      |
+| ------------------------- | -------------------------------------------- |
+| Interactive mode          | :EasyAlign[!] [OPTIONS]                      |
+| Using predefined rules    | :EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS] |
+| Using regular expressions | :EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]      |
 
-    vnoremap <silent> <Enter> :EasyAlign<cr>
 
-With this mapping, you can align selected lines with a few keystrokes.
+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 <silent> <Enter> :EasyAlign<Enter>
+
+With this mapping, you can align selected lines of text 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        Alignment around 1st delimiters
-    2        Alignment around 2nd delimiters
+2. Optional: Enter keys to select alignment mode (left, right, or center)
+3. Optional: N-th delimiter (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
     ...
-    *        Alignment around all delimiters (recursive)
-4. Delimiter
+4. Delimiter key for the predefined rules (a single keystroke)
     <space>  General alignment around whitespaces
     =        Operators containing equals sign (=, ==, !=, +=, &&=, ...)
     :        Suitable for formatting JSON or YAML
@@ -34,89 +52,474 @@ With this mapping, you can align selected lines with a few keystrokes.
     ,        Multi-line method arguments. CSV.
     |        Table markdown
 
-During the key sequence, <Enter> key will toggle right-justification mode.
+    (You can override these default rules or define your own rules with
+    `g:easy_align_delimiters`, which will be described in the later section.)
+
+During the key sequence, <Enter> key will toggle right-align mode.
 
 Examples:
 
-  <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><Enter>=  Right-justified alignment around 1st equals signs
-  <Enter><space>   Alignment around 1st whitespace
-  <Enter>2<space>  Alignment around 2nd whitespace
-  <Enter>:         Alignment around 1st colon
+  <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-alignment around 1st equals signs
+  <Enter><Enter>**=  Right-left alternating alignment around all equals signs
 
 
-EasyAlignRight                                           *EasyAlignRight*
+Instead of finishing the command with a predefined delimiter key, you can type
+in a regular expression after `<CTRL-/>` or `<CTRL-X>` key.
+For example, if you want to align text around all occurrences of numbers:
+
+- <Enter>
+- *
+- <CTRL-/> (or <CTRL-X> on Gvim)
+  - [0-9]\+
+
+
+While in interactive mode, you can adjust some of the alignment options using
+special shortcut keys listed below. The meanings of the options will be
+described in the following sections.
+
+| Key     | Option           | Values                                       |
+| ------- | ---------------- | -------------------------------------------- |
+| CTRL-I  | indentation      | shallow, deep, none, keep                    |
+| CTRL-L  | left_margin      | Input number or string                       |
+| CTRL-R  | right_margin     | Input number or string                       |
+| CTRL-D  | delimiter_align  | left, center, right                          |
+| CTRL-U  | ignore_unmatched | 0, 1                                         |
+| CTRL-G  | ignore_groups    | [], [String], [Comment], [String, Comment]   |
+| CTRL-O  | mode_sequence    | Input string of /[lrc]+\*{0,2}/              |
+| <Left>  | stick_to_left    | { 'stick_to_left': 1, 'left_margin': 0 }     |
+| <Right> | stick_to_left    | { 'stick_to_left': 0, 'left_margin': 1 }     |
+| <Down>  | *_margin         | { 'left_margin': 0, 'right_margin': 0 }      |
+
+                                              *g:easy_align_last_command*
+
+After a successful alignment, you can repeat the same operation using the
+repeatable, non-interactive command recorded in `g:easy_align_last_command`.
+
+    :<C-R>=g:easy_align_last_command<Enter><Enter>
+
+
+Left/right/center mode switch in interactive mode
+-------------------------------------------------------------------------
+                                         *g:easy_align_interactive_modes*
+                                    *g:easy_align_bang_interactive_modes*
+
+In interactive mode, you can choose the alignment mode you want by pressing
+enter keys. The non-bang command, `:EasyAlign` starts in left-alignment mode
+and changes to right and center mode as you press enter keys, while the bang
+version first starts in right-alignment mode.
+
+- `:EasyAlign`
+  - Left, Right, Center
+- `:EasyAlign!`
+  - Right, Left, Center
+
+If you do not prefer this default mode transition, you can define your own
+settings as follows.
+
+    let g:easy_align_interactive_modes = ['l', 'r']
+    let g:easy_align_bang_interactive_modes = ['c', 'r']
+
+
+Using EasyAlign in command line
 -------------------------------------------------------------------------
 
-EasyAlignRight is the right-justified version of EasyAlign command.
+Instead of going into the interactive mode, you can type in arguments to
+`:EasyAlign` command.
+
+    " Using predefined alignment rules
+    :EasyAlign[!] [N-th] DELIMITER_KEY [OPTIONS]
+
+    " Using arbitrary regular expressions
+    :EasyAlign[!] [N-th] /REGEXP/ [OPTIONS]
+
+For example, when aligning the following lines around colons and semi-colons,
+
+    apple;:banana::cake
+    data;;exchange:;format
+
+try these commands:
+
+    :EasyAlign /[:;]\+/
+    :EasyAlign 2/[:;]\+/
+    :EasyAlign */[:;]\+/
+    :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 in Vim dictionary
+format.
+
+    :EasyAlign * /[:;]\+/ { 'stick_to_left': 1, 'left_margin': 0 }
+
+Then we get:
+
+    apple;: banana::   cake
+    data;;  exchange:; format
+
+Option names are fuzzy-matched, so you can write as follows:
+
+    :EasyAlign * /[:;]\+/ { 'stl': 1, 'l': '' }
+
+You can even omit spaces between the arguments, so concisely (or cryptically):
+
+    :EasyAlign*/[:;]\+/{'s':1,'l':''}
+
+Nice. But let's make it even shorter. Option values can be written in shorthand
+notation.
+
+    :EasyAlign*/[:;]\+/s1l0
+
+The following table summarizes the shorthand notation.
+
+| Option           | Expression |
+| --------------   | ---------- |
+| left_margin      | l[0-9]+    |
+| right_margin     | r[0-9]+    |
+| stick_to_left    | s[01]      |
+| ignore_unmatched | iu[01]     |
+| ignore_groups    | ig\[.*\]   |
+| delimiter_align  | d[lrc]     |
+| mode_sequence    | m[lrc*]+   |
+| indentation      | i[ksdn]    |
+
+For your information, the same thing can be done in the interactive mode as well
+with the following key combination.
+
+    - <Enter>
+    - *
+    - <Left>
+    - <CTRL-/> (or <CTRL-X> on GVim)
+      - [:;]\+
 
 
 Partial alignment in blockwise-visual mode
 -------------------------------------------------------------------------
 
-In blockwise-visual mode (`CTRL-V`), EasyAlign command aligns only
-the selected parts, instead of the whole lines in the range.
+In blockwise-visual mode (CTRL-V), EasyAlign command aligns only
+the selected text in the block, instead of the whole lines in the range.
 
 
-
-Defining custom alignment rules                 *g:easy_align_delimiters*
+Alignment options
 -------------------------------------------------------------------------
 
-    let g:easy_align_delimiters = {
-    \ '/': { 'pattern': '//*' },
-    \ 'x': {
-    \     'pattern':       '[xX]',
-    \     'margin_left':   ' <<<',
-    \     'margin_right':  '>>> ',
-    \     'stick_to_left': 0
-    \   }
-    \ }
+Available options are as follows.
+
+| Atrribute        | Type             | Default                       |
+| ---------------- | ---------------- | ----------------------------- |
+| left_margin      | number or string | 1                             |
+| right_margin     | number or string | 1                             |
+| stick_to_left    | boolean          | 0                             |
+| ignore_unmatched | boolean          | 1                             |
+| ignore_groups    | array            | ['String', 'Comment']         |
+| delimiter_align  | string           | 'r'                           |
+|                  |                  |   (right, left, center)       |
+| indentation      | string           | 'k'                           |
+|                  |                  |   (keep, shallow, deep, none) |
+| mode_sequence    | string           | (Depends on N-th param and    |
+|                  |                  |  selected alignment mode)     |
+
+There are 4 ways to set alignment options (from lowest precedence to highest):
+
+1. Some option values can be set with corresponding global variables
+2. Option values can be specified in the definition of each alignment rule
+3. Option values can be given as arguments to :EasyAlign command
+4. Option values can be set in interactive mode using special shortcut keys
+
+| Option           | Shortcut key    | Abbreviated | Global variable               |
+| ---------------- | --------------- | ----------- | ----------------------------- |
+| left_margin      | CTRL-L          | l[0-9]+     |                               |
+| right_margin     | CTRL-R          | r[0-9]+     |                               |
+| stick_to_left    | <Left>, <Right> | s[01]       |                               |
+| ignore_groups    | CTRL-G          | ig\[.*\]    | `g:easy_align_ignore_groups`    |
+| ignore_unmatched | CTRL-U          | iu[01]      | `g:easy_align_ignore_unmatched` |
+| indentation      | CTRL-I          | i[ksdn]     | `g:easy_align_indentation`      |
+| delimiter_align  | CTRL-D          | d[lrc]      | `g:easy_align_delimiter_align`  |
+| mode_sequence    | CTRL-O          | m[lrc*]+    |                               |
 
 
-Handling unmatched lines                  *g:easy_align_ignore_unmatched*
+Ignoring delimiters in comments or strings   *g:easy_align_ignore_groups*
 -------------------------------------------------------------------------
 
-EasyAlign by default ignores lines without the matching delimiters
-(except in right-justification mode).
-This is to ignore interleaved comments commonly found in code.
+EasyAlign can be configured to ignore delimiters in certain syntax
+highlight groups, such as code comments or strings. By default, delimiters
+that are highlighted as code comments or strings are ignored.
 
-For example, when aligning the following code,
+    " Default:
+    "   If a delimiter is in a highlight group whose name matches
+    "   any of the followings, it will be ignored.
+    let g:easy_align_ignore_groups = ['Comment', 'String']
+
+For example, the following paragraph
 
     {
-      # Quantity of apples
+      # Quantity of apples: 1
       apple: 1,
-      # Quantity of bananas
+      # Quantity of bananas: 2
+      bananas: 2,
+      # Quantity of grape:fruits: 3
+      'grape:fruits': 3
+    }
+
+becomes as follows on '<Enter>:' (or `:EasyAlign:`)
+
+    {
+      # Quantity of apples: 1
+      apple:          1,
+      # Quantity of bananas: 2
+      bananas:        2,
+      # Quantity of grape:fruits: 3
+      'grape:fruits': 3
+    }
+
+Naturally, this feature only works when syntax highlighting is enabled.
+
+You can change the default rule by using one of these 4 methods.
+
+1. Press CTRL-G in interactive mode to switch groups
+2. Define global `g:easy_align_ignore_groups` list
+3. Define a custom rule in `g:easy_align_delimiters` with 'ignore_groups' option
+4. Provide 'ignore_groups' option to `:EasyAlign` command.
+   e.g. :EasyAlign:ig[]
+
+For example if you set 'ignore_groups' option to be an empty list, you get
+
+    {
+      # Quantity of apples:  1
+      apple:                 1,
+      # Quantity of bananas: 2
+      bananas:               2,
+      # Quantity of grape:   fruits: 3
+      'grape:                fruits': 3
+    }
+
+
+Ignoring unmatched lines                  *g:easy_align_ignore_unmatched*
+-------------------------------------------------------------------------
+
+'ignore_unmatched' option determines how EasyAlign command processes lines that
+do not have N-th delimiter.
+
+1. In left-alignment mode, they are ignored
+2. In right or center-alignment mode, they are not ignored, and the last
+   tokens from those lines are aligned as well as if there is an invisible
+   trailing delimiter at the end of each line
+3. If 'ignore_unmatched' is 1, they are ignored regardless of the alignment mode
+4. If 'ignore_unmatched' is 0, they are not ignored regardless of the mode
+
+Let's take an example.
+When we align the following code block around the (1st) colons,
+
+    {
+      apple: proc {
+        this_line_does_not_have_a_colon
+      },
       bananas: 2,
-      # Quantity of grapefruits
       grapefruits: 3
     }
 
 this is usually what we want.
 
     {
-      # Quantity of apples
-      apple:       1,
-      # Quantity of bananas
+      apple:       proc {
+        this_line_does_not_have_a_colon
+      },
       bananas:     2,
-      # Quantity of grapefruits
       grapefruits: 3
     }
 
-However, this default behavior is configurable.
+However, we can override this default behavior by setting 'ignore_unmatched'
+option to zero using one of the following methods.
 
-    let g:easy_align_ignore_unmatched = 0
+1. Press CTRL-U in interactive mode to toggle 'ignore_unmatched' option
+2. Set the global `g:easy_align_ignore_unmatched` variable to 0
+3. Define a custom alignment rule with 'ignore_unmatched' option set to 0
+4. Provide 'ignore_unmatched' option to `:EasyAlign` command.
+   e.g. :EasyAlign:iu0
 
 Then we get,
 
     {
-      # Quantity of apples
-      apple:                     1,
-      # Quantity of bananas
-      bananas:                   2,
-      # Quantity of grapefruits
-      grapefruits:               3
+      apple:                             proc {
+        this_line_does_not_have_a_colon
+      },
+      bananas:                           2,
+      grapefruits:                       3
     }
 
+
+Aligning delimiters of different lengths   *g:easy_align_delimiter_align*
+-------------------------------------------------------------------------
+
+Global `g:easy_align_delimiter_align` option and rule-wise/command-wise
+'delimiter_align' option determines how matched delimiters of different
+lengths are aligned.
+
+    apple = 1
+    banana += apple
+    cake ||= banana
+
+By default, delimiters are right-aligned as follows.
+
+    apple    = 1
+    banana  += apple
+    cake   ||= banana
+
+However, with ':EasyAlign=dl', delimiters are left-aligned.
+
+    apple  =   1
+    banana +=  apple
+    cake   ||= banana
+
+And on ':EasyAlign=dc', center-aligned.
+
+    apple   =  1
+    banana +=  apple
+    cake   ||= banana
+
+In interactive mode, you can change the option value with `CTRL-D` key.
+
+
+Adjusting indentation                          *g:easy_align_indentation*
+-------------------------------------------------------------------------
+
+By default :EasyAlign command keeps the original indentation of the lines.
+But then again we have 'indentation' option. See the following example.
+
+    # Lines with different indentation
+      apple = 1
+        banana = 2
+          cake = 3
+            daisy = 4
+         eggplant = 5
+
+    # Default: _k_eep the original indentation
+    #   :EasyAlign=
+      apple       = 1
+        banana    = 2
+          cake    = 3
+            daisy = 4
+         eggplant = 5
+
+    # Use the _s_hallowest indentation among the lines
+    #   :EasyAlign=is
+      apple    = 1
+      banana   = 2
+      cake     = 3
+      daisy    = 4
+      eggplant = 5
+
+    # Use the _d_eepest indentation among the lines
+    #   :EasyAlign=id
+            apple    = 1
+            banana   = 2
+            cake     = 3
+            daisy    = 4
+            eggplant = 5
+
+    # Indentation: _n_one
+    #   :EasyAlign=in
+    apple    = 1
+    banana   = 2
+    cake     = 3
+    daisy    = 4
+    eggplant = 5
+
+
+Notice that 'idt' is fuzzy-matched to 'indentation'.
+
+In interactive mode, you can change the option value with `CTRL-I` key.
+
+
+Alignments over multiple occurrences of delimiters
+-------------------------------------------------------------------------
+
+As stated above, "N-th" parameter is used to target specific occurrences of
+the delimiter when it appears multiple times in each line.
+
+To recap:
+
+    " Left-alignment around the FIRST occurrences of delimiters
+    :EasyAlign =
+
+    " Left-alignment around the SECOND occurrences of delimiters
+    :EasyAlign 2=
+
+    " Left-alignment around the LAST occurrences of delimiters
+    :EasyAlign -=
+
+    " Left-alignment around ALL occurrences of delimiters
+    :EasyAlign *=
+
+    " Left-right ALTERNATING alignment around all occurrences of delimiters
+    :EasyAlign **=
+
+    " Right-left ALTERNATING alignment around all occurrences of delimiters
+    :EasyAlign! **=
+
+In addition to these, you can fine-tune alignments over multiple occurrences of
+the delimiters with 'mode_sequence' option. (The option can also be set
+in interactive mode with the special key CTRL-O)
+
+    " Left alignment over the first two occurrences of delimiters
+    :EasyAlign = { 'mode_sequence': 'll' }
+
+    " Right, left, center alignment over the 1st to 3rd occurrences of delimiters
+    :EasyAlign = { 'm': 'rlc' }
+
+    " Using shorthand notation
+    :EasyAlign = mrlc
+
+    " Right, left, center alignment over the 2nd to 4th occurrences of delimiters
+    :EasyAlign 2=mrlc
+
+    " (*) Repeating alignments (default: l, r, or c)
+    "   Right, left, center, center, center, center, ...
+    :EasyAlign *=mrlc
+
+    " (**) Alternating alignments (default: lr or rl)
+    "   Right, left, center, right, left, center, ...
+    :EasyAlign **=mrlc
+
+    " Right, left, center, center, center, ... repeating alignment
+    " over the 3rd to the last occurrences of delimiters
+    :EasyAlign 3=mrlc*
+
+    " Right, left, center, right, left, center, ... alternating alignment
+    " over the 3rd to the last occurrences of delimiters
+    :EasyAlign 3=mrlc**
+
+
+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': '//\+\|/\*\|\*/', 'ignore_groups': ['String'] },
+    \ '#': { 'pattern': '#\+', 'ignore_groups': ['String'] },
+    \ ']': {
+    \     'pattern':       '[[\]]',
+    \     'left_margin':   0,
+    \     'right_margin':  0,
+    \     'stick_to_left': 0
+    \   },
+    \ ')': {
+    \     'pattern':       '[()]',
+    \     'left_margin':   0,
+    \     'right_margin':  0,
+    \     'stick_to_left': 0
+    \   }
+    \ }
+
+

plugin/easy_align.vim

@@ -1,7 +1,29 @@
-if exists("g:easy_align_plugin_loaded")
+" Copyright (c) 2013 Junegunn Choi
+"
+" MIT License
+"
+" Permission is hereby granted, free of charge, to any person obtaining
+" a copy of this software and associated documentation files (the
+" "Software"), to deal in the Software without restriction, including
+" without limitation the rights to use, copy, modify, merge, publish,
+" distribute, sublicense, and/or sell copies of the Software, and to
+" permit persons to whom the Software is furnished to do so, subject to
+" the following conditions:
+"
+" The above copyright notice and this permission notice shall be
+" included in all copies or substantial portions of the Software.
+"
+" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+if exists("g:loaded_easy_align_plugin")
   finish
 endif
-let g:easy_align_plugin_loaded = 1
+let g:loaded_easy_align_plugin = 1
 
-command! -nargs=* -range EasyAlign <line1>,<line2>call easy_align#align(0, <f-args>)
-command! -nargs=* -range EasyAlignRight <line1>,<line2>call easy_align#align(1, <f-args>)
+command! -nargs=* -range -bang EasyAlign <line1>,<line2>call easy_align#align('<bang>' == '!', <q-args>)

test/basic.md

@@ -0,0 +1,273 @@
+" :source run.vim
+" @a
+
+Paul McCartney 1942
+George Harrison 1943
+Ringo Starr 1940
+Pete Best 1941
+
+| Option| Type | Default | Description |
+|--|--|--|--|
+| threads | Fixnum | 1 | number of threads in the thread pool |
+|queues |Fixnum | 1 | number of concurrent queues |
+|queue_size | Fixnum | 1000 | size of each queue |
+|   interval | Numeric | 0 | dispatcher interval for batch processing |
+|batch | Boolean | false | enables batch processing mode |
+ |batch_size | Fixnum | nil | number of maximum items to be assigned at once |
+ |logger | Logger | nil | logger instance for debug logs |
+
+aaa,   bb,c
+d,eeeeeee
+fffff, gggggggggg,
+h, ,           ii
+j,,k
+
+```ruby
+
+a =
+a = 1
+bbbb .= 2
+ccccccc = 3
+ccccccccccccccc
+ddd = #
+eeee === eee = eee = eee=f
+fff = ggg += gg &&= gg
+g != hhhhhhhh == # 8
+i   := 5
+i     %= 5
+i       *= 5
+j     =~ 5
+j   >= 5
+aa      =>         123
+aa <<= 123
+aa        >>= 123
+bbb               => 123
+c     => 1233123
+d   =>      123
+dddddd &&= 123
+dddddd ||= 123
+dddddd /= 123
+gg <=> ee
+
+options = { :caching => nil,
+            :versions => 3,
+            "cache=blocks" => false }.merge(options)
+
+apple = 1 # comment not aligned
+banana = 'Gros Michel' # comment 2
+
+# let g:easy_align_delimiters = { '#': { 'pattern': '#\+', 'ignores': ['String'] } }
+
+apple = 1 # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'Gros Michel' # comment 2
+
+```
+
+```yaml
+
+mysql:
+  # JDBC driver for MySQL database:
+  driver: com.mysql.jdbc.Driver
+  # JDBC URL for the connection (jdbc:mysql://HOSTNAME/DATABASE)
+  url: jdbc:mysql://localhost/test
+  database: test
+  "user:pass":r00t:pa55
+
+```
+```c
+
+/* a */ b = c
+aa >= bb
+// aaa = bbb = cccc
+/* aaaa = */ bbbb   === cccc   " = dddd = " = eeee
+aaaaa /* bbbbb */      == ccccc /* != eeeee = */ === fffff
+
+```
+
+my_object
+      .method1.chain
+    .second_method.call
+      .third.call
+     .method_4.execute
+
+my_object.
+      method1.chain.
+    second_method.call.
+      third.call.
+     method_4.execute
+
+   | Option| Type | Default | Description |
+    |--|--|--|--|
+       | threads | Fixnum | 1 | number of threads in the thread pool |
+  |queues |Fixnum | 1 | number of concurrent queues |
+   |queue_size | Fixnum | 1000 | size of each queue |
+    |   interval | Numeric | 0 | dispatcher interval for batch processing |
+       |batch | Boolean | false | enables batch processing mode |
+   |batch_size | Fixnum | nil | number of maximum items to be assigned at once |
+   |logger | Logger | nil | logger instance for debug logs |
+
+
+```c
+
+const char* str = "Hello";
+int64_t count = 1 + 2;
+static double pi = 3.14;
+static std::map<std::string, float>* scores =    pointer;
+
+```
+
+Paul McCartney 1942
+George Harrison 1943
+Ringo Starr 1940
+Pete Best 1941
+
+...-.-----
+..--..----
+.---...---
+----....--
+.---.....-
+..--......
+...-.....-
+
+  apple = 1
+    banana = 2
+      cake = 3
+        daisy = 4
+     eggplant = 5
+
+
+```c
+
+int a = 1;
+long b = 2;
+float c = 3;
+string d = 4;
+// this line should not get aligned
+long int e = 5;
+std::map f;
+std::map g; /* this? */
+short h /* how about this? */ = 6;
+string i = "asdf";
+
+```
+
+```ruby
+
+a =
+a = 1
+bbbb .= 2
+ccccccc = 3
+ccccccccccccccc
+# eeeeeeeeeeeeeeee
+e # asdf
+ddd = #
+eeee === eee = eee = eee=f
+fff = ggg += gg &&= gg
+g != hhhhhhhh == # 8
+i   := 5
+i     %= 5
+i       *= 5
+j     =~ 5
+j   >= 5
+aa      =>         123
+aa <<= 123
+aa        >>= 123
+bbb               => 123
+c     => 1233123
+d   =>      123
+dddddd &&= 123
+dddddd ||= 123
+dddddd /= 123
+gg <=> ee
+
+a = 1
+bb = 22
+ccc = 333
+dddd = "asdf"
+
+```
+
+a a a a a
+bbb bbb bbb bbb bbb
+ccccc ccccc ccccc ccccc ccccc
+  d ddd dddd ddd d
+
+aaaaa = 123456778901234567890 =
+bbbbbbbbbb = 12345 =
+
+aaaaa = 123456778901234567890 =
+cccccccccccccccccc = 123 =
+
+aaaaa = 123456778901234567890 =
+cccccccccccccccccc = 12345678 =
+
+aaaaa = 12345 =
+bbbbbbbbbb = 123456778901234567890       =
+
+aaaaa =             12345
+bbbbbbbbbb = 123456778901234567890
+
+123456 789
+1234567890 1
+
+1234 56
+123456 7890
+
+ aaaaa = 123456778901234567890 =
+     cccccccccccccccccc =       12345678 =
+
+```
+ aaaaa =   123456778901234567890 =
+cccccccccccccccccc =12345678 =
+
+            aaaa             = 123456778901234567890 =
+     cccccccccccccccccc      = 12345678 =
+
+            aaaaaaaaaaaaa = 123456778901234567890 =
+cc = 12345678 =
+
+           aaaaaaaaaaa= 123
+                       a = 123
+
+           aaaaaaaaaaaa= 123
+                       a = 123
+
+         aaaaaaaaaaaa = 123
+       aaaaaaaaaaa = 123
+      aaaaaaaaaa  = 123
+     aaa     = 123
+    aa      = 123
+   a      = 123
+
+            aaaa = 123456778901234567890 =
+cccccccccccccc = 12345678 =
+
+              aaaa = 123456778901234567890 =
+               bbbbbb = 4
+cccccccccccccccccc = 12345678 =
+
+                    aaaa = 123456778901234567890 =
+     cccccccccccccccccc = 12345678 =
+
+                    aaaaa                     = 123456778901234567890 =
+                     cc                       = 12345678 =
+
+=aaaaa = 123456778901234567890 =
+=    cccccccccccccccccc = 12345678 =
+
+```
+
+a,,bbb
+aa,,bb
+aaa,,b
+aaaa,,
+aaa,b,
+aa,bb,
+a,bbb,
+
+1 22222 33 444 555 6666 7 888
+11 222 3333 4 55 6666 77 888
+111 22 333 444 55555 6666 7 88888
+1111 2 33 444 555 66 777 8
+

test/basic.script

@@ -0,0 +1 @@
+4Gvipjyvip

test/regexp.expected

@@ -0,0 +1,128 @@
+" :source run.vim
+" @a
+
+apple;:banana  :: cake
+data;;exchange :; format
+
+apple ;: banana   ::   cake
+ data ;; exchange :; format
+
+apple ;:   banana :: cake
+data  ;; exchange :; format
+
+apple ;:____banana::cake
+data  ;;____exchange:;format
+
+apple ;  : banana   :  : cake
+data  ;  ; exchange :  ; format
+
+ap  pl  e;  :b  an  an  a:  :c  ak e
+da  ta  ;;  ex  ch  an  ge  :;  fo  rm  at
+
+ap ple;:banana::cake
+da ta;;exchange:;format
+
+apple???;:~~~banana???::~~~  cake
+data???;;~~~ exchange???:;~~~format
+
+apple;: banana::cake
+data;;  exchange:;format
+
+apple<<<;:>>>banana::cake
+data <<<;;>>>exchange:;format
+
+apple ;: banana::cake
+data  ;; exchange:;format
+
+apple;:banana  :: cake
+data;;exchange :; format
+
+apple ;: banana   :: cake
+data  ;; exchange :; format
+
+apple ;: banana   :: cake
+data  ;; exchange :; format
+
+apple ;: banana   :: cake
+data  ;; exchange :; format
+
+apple ;: banana   :: cake
+data  ;; exchange :; format
+
+apple ;: banana::cake
+data  ;; exchange:;format
+
+apple ; :banana::cake
+data  ;  ; exchange: ; format
+
+apple ; :banana::cake
+data  ; ;exchange:;format
+
+apple ; :banana::cake
+data  ; ;exchange:;format
+
+apple;:banana::cake
+data;;exchange:;format
+
+apple;:         banana: : cake
+data;;exchange: ;format
+
+apple;:banana: :cake
+data;;exchange:;format
+
+apple;:banana: :cake
+data;;exchange:;format
+
+apple;:         banana: : cake
+data;;exchange: ;format
+
+apple;:banana:: cake
+data;;exchange: ;format
+
+apple;:         banana: : cake
+data;;exchange: ;format
+
+apple;:         banana::cake
+data;;exchange: ;format
+
+```ruby
+apple = 1                # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'Gros Michel'   # comment 2
+```
+
+a()p()p()l()e();():()b()a()n()a()n()a():():()c()a()k()e(
+d()a()t()a();();()e()x()c()h()a()n()g()e():();()f()o()r()m()a()t(
+
+apple  ;: banana   ::  cake
+ data  ;;exchange  :;format
+
+apple ;:  banana  ::   cake
+ data ;; exchange :; format
+
+apple;:banana  ::cake
+data ;;exchange:;format
+
+apple   ;:   banana   ::     cake
+data   ;;    exchange   :;   format
+
+a+=         1
+bb==#       2
+ccc=        3
+dddd=>      4
+
+apple;:     banana::    cake
+ data;;   exchange:;   format
+
+```ruby
+apple = 1       # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'Gros  Michel'   # comment 2
+```
+
+```ruby
+apple = 1              # comment not aligned
+apricot = 'DAD'        + 'F#AD'
+banana = 'Gros Michel' # comment 2
+```
+

test/regexp.md

@@ -0,0 +1,12 @@
+" :source run.vim
+" @a
+
+apple;:banana::cake
+data;;exchange:;format
+
+```ruby
+apple = 1 # comment not aligned
+apricot = 'DAD' + 'F#AD'
+banana = 'Gros Michel' # comment 2
+```
+

test/regexp.script

@@ -0,0 +1 @@
+4Gvipjyvip:EasyAlign:

test/run.vim

@@ -0,0 +1,51 @@
+e!
+
+function! GFM()
+  let syntaxes = {
+  \ 'ruby':   'syntax/ruby.vim',
+  \ 'yaml':   'syntax/yaml.vim',
+  \ 'vim':    'syntax/vim.vim',
+  \ 'sh':     'syntax/sh.vim',
+  \ 'python': 'syntax/python.vim',
+  \ 'java':   'syntax/java.vim',
+  \ 'c':      'syntax/c.vim'
+  \ }
+
+  for [lang, syn] in items(syntaxes)
+    unlet b:current_syntax
+    silent! exec printf("syntax include @%s %s", lang, syn)
+    exec printf("syntax region %sSnip matchgroup=Snip start='```%s' end='```' contains=@%s",
+                \ lang, lang, lang)
+  endfor
+  let b:current_syntax='mkd'
+
+  syntax sync fromstart
+endfunction
+
+silent! unlet g:easy_align_delimiters
+silent! unlet g:easy_align_ignore_unmatched
+silent! unlet g:easy_align_ignores
+
+vnoremap <silent> <Enter> :EasyAlign<cr>
+
+noremap  <silent> <C-k> <nop>
+noremap  <silent> <C-j> <nop>
+noremap  <silent> <C-h> <nop>
+noremap  <silent> <C-l> <nop>
+vnoremap <silent> <C-k> <nop>
+vnoremap <silent> <C-j> <nop>
+vnoremap <silent> <C-h> <nop>
+vnoremap <silent> <C-l> <nop>
+
+set nolazyredraw
+set buftype=nofile
+set colorcolumn=
+
+silent! ScrollPositionHide
+
+call GFM()
+
+normal gg
+let @b=system('cat '. expand('%:p:r') . '.script')
+let @a='@b:vert diffsplit ' . expand('%:p:r') . '.expected
+'