*vim-multiple-cursors.txt* True Sublime Text multiple selection in Vim

                    ____  _       __
   ____ ___  __  __/ / /_(_)___  / /__     _______  ________________  __________
  / __ `__ \/ / / / / __/ / __ \/ / _ \   / ___/ / / / ___/ ___/ __ \/ ___/ ___/
 / / / / / / /_/ / / /_/ / /_/ / /  __/  / /__/ /_/ / /  (__  ) /_/ / /  (__  )
/_/ /_/ /_/\__,_/_/\__/_/ .___/_/\___/   \___/\__,_/_/  /____/\____/_/  /____/
                       /_/


                              Reference Manual~


==============================================================================

CONTENTS                                            *multiple-cursors-contents*
    1.Intro...................................|multiple-cursors-intro|
    2.Usage...................................|multiple-cursors-usage|
    3.Mappings................................|multiple-cursors-mappings|
    4.Global Options..........................|multiple-cursors-global-options|
    5.Interactions with other plugins.........|multiple-cursors-other-plugins|
    6.Highlight...............................|multiple-cursors-highlight|
    7.FAQ.....................................|multiple-cursors-faq|
    8.Contributing............................|multiple-cursors-contributing|
    9.License.................................|multiple-cursors-license|
   10.Credit..................................|multiple-cursors-credit|
   11.References..............................|multiple-cursors-references|

==============================================================================
1. Intro                                              *multiple-cursors-intro*

There [1] have [2] been [3] many [4] attempts [5] at bringing Sublime Text's
awesome multiple selection [6] feature into Vim, but none so far have been in
my opinion a faithful port that is simplistic to use, yet powerful and
intuitive enough for an existing Vim user. *vim-multiple-cursors* is yet
another attempt at that.

==============================================================================
2. Usage                                              *multiple-cursors-usage*

normal mode / visual mode~

    - start:      `<C-n>` start multicursor and add a virtual cursor + visual selection on the match
        + next:   `<C-n>` add a new virtual cursor + visual selection on the next match
        + skip:   `<C-x>` skip the next match
        + prev:   `<C-p>` remove current virtual cursor + visual selection and go back on previous match
    - select all: `<A-n>` start muticursor and directly select all matches

You can now change the virtual cursors + visual selection with |visual-mode| commands.
For instance: `c`, `s`, `I`, `A` work without any issues.
You could also go to |normal-mode| by pressing `v` and use normal commands there.

At any time, you can press `<Esc>` to exit back to regular Vim.

NOTE: start with `g<C-n>` to match without boundaries (behaves like `g*` instead of `*`, see |gstar|)

visual mode when multiple lines are selected~

    - start: `<C-n>` add virtual cursors on each line

You can now change the virtual cursors with |normal-mode| commands.
For instance: `ciw`.

command~

The command `MultipleCursorsFind` accepts a range and a pattern (regexp), it
creates a visual cursor at the end of each match.
If no range is passed in, then it defaults to the entire buffer.

==============================================================================
3. Mappings                                        *multiple-cursors-mappings*

If you don't like the plugin taking over your favorite key bindings, you can
turn off the default with >

    let g:multi_cursor_use_default_mapping=0

    " Default mapping
    let g:multi_cursor_start_word_key      = '<C-n>'
    let g:multi_cursor_select_all_word_key = '<A-n>'
    let g:multi_cursor_start_key           = 'g<C-n>'
    let g:multi_cursor_select_all_key      = 'g<A-n>'
    let g:multi_cursor_next_key            = '<C-n>'
    let g:multi_cursor_prev_key            = '<C-p>'
    let g:multi_cursor_skip_key            = '<C-x>'
    let g:multi_cursor_quit_key            = '<Esc>'
<

NOTE: Please make sure to always map something to |g:multi_cursor_quit_key|,
otherwise you'll have a tough time quitting from multicursor mode.

==============================================================================
4. Global Options                            *multiple-cursors-global-options*

Currently there are four additional global settings one can tweak:

*g:multi_cursor_support_imap* (Default: 1)

If set to 0, insert mappings won't be supported in |insert-mode| anymore.

*g:multi_cursor_exit_from_visual_mode* (Default: 0)

If set to 0, then pressing |g:multi_cursor_quit_key| in |visual-mode| will quit
and delete all existing cursors, skipping normal mode with multiple cursors.

*g:multi_cursor_exit_from_insert_mode* (Default: 0)

If set to 1, then pressing |g:multi_cursor_quit_key| in |insert-mode| will quit
and delete all existing cursors, skipping normal mode with multiple cursors.

*g:multi_cursor_normal_maps* (Default: see below)

`{'@': 1, 'F': 1, 'T': 1, '[': 1, '\': 1, ']': 1, '!': 1, '"': 1, 'c': 1, 'd': 1, 'f': 1, 'g': 1, 'm': 1, 'q': 1, 'r': 1, 't': 1, 'y': 1, 'z': 1, '<': 1, '=': 1, '>': 1}`

Any key in this map (values are ignored) will cause multi-cursor _Normal_ mode
to pause for map completion just like normal vim. Otherwise keys mapped in
normal mode will "fail to replay" when multiple cursors are active. For
example: `{'d':1}` makes normal-mode command `dw` work in multi-cursor mode.

The default list contents should work for anybody, unless they have remapped a
key from an operator-pending command to a non-operator-pending command or
vice versa.

These keys must be manually listed because vim doesn't provide a way to
automatically see which keys _start_ mappings, and trying to run motion commands
such as `j` as if they were operator-pending commands can break things.

*g:multi_cursor_visual_maps* (Default: )

`{'T': 1, 'a': 1, 't': 1, 'F': 1, 'f': 1, 'i': 1}`

Same principle as |g:multi_cursor_normal_maps|

==============================================================================
5. Interactions with other plugins                    *multiple-cursors-other-plugins*

Other plugins may be incompatible in insert mode. That is why we provide
hooks to disable those plug-ins when vim-multiple-cursors is active:

For example, if you are using `Neocomplete`, add this to your vimrc to prevent
conflict:
 >
    function! Multiple_cursors_before()
      if exists(':NeoCompleteLock')==2
        exe 'NeoCompleteLock'
      endif
    endfunction

    function! Multiple_cursors_after()
      if exists(':NeoCompleteUnlock')==2
        exe 'NeoCompleteUnlock'
      endif
    endfunction

Plugins themselves can register |User| |autocommand| on `MultipleCursorsPre` and
`MultipleCursorsPost` for automatic integration.

==============================================================================
6. Highlight                                          *multiple-cursors-highlight*
>
The plugin uses the highlight group `multiple_cursors_cursor` and
`multiple_cursors_visual` to highlight the virtual cursors and their visual
selections respectively. You can customize them by putting something similar
like the following in your vimrc: >
    " Default highlighting (see help :highlight and help :highlight-link)
    highlight multiple_cursors_cursor term=reverse cterm=reverse gui=reverse
    highlight link multiple_cursors_visual Visual

==============================================================================
7. FAQ                                              *multiple-cursors-faq*

Q:  Pressing <i> after selecting words with <C-n> makes the plugin hang, why?
A:  When selecting words with <C-n>, the plugin behaves like in `visual` mode.
    Once you pressed <i>, you can still press <I> to insert text.

Q:  <A-n> doesn't seem to work in VIM but works in gVIM, why?
A:  This is a well known terminal/Vim [9], different terminal have different
    ways to send `Alt+key`.  Try adding this in your `.vimrc` and make sure
    to replace the string: >
    if !has('gui_running')
      map "in Insert mode, type Ctrl+v Alt+n here" <A-n>
    endif
Or remap the following: >
    g:multi_cursor_start_key
    g:multi_cursor_select_all_key

Q:  <C-n> doesn't seem to work in gVIM?
A:  Try setting `set selection=inclusive` in your `~/.gvimrc`

Q:  deoplete insert giberrish, how to fix this?
A:  use the `Multiple_cursors` functions, add this in your vimrc: >
    func! Multiple_cursors_before()
      if deoplete#is_enabled()
        call deoplete#disable()
        let g:deoplete_is_enable_before_multi_cursors = 1
      else
        let g:deoplete_is_enable_before_multi_cursors = 0
      endif
    endfunc
    func! Multiple_cursors_after()
      if g:deoplete_is_enable_before_multi_cursors
        call deoplete#enable()
      endif
    endfunc

Q:  is it also working on Mac?
A:  On Mac OS, MacVim[10] is known to work.

Q:  How can I select `n` keywords with several keystrokes? `200<C-n>` does not work.
A:  You can use :MultipleCursorsFind keyword. I have this binding in my vimrc: >
    nnoremap <silent> <M-j> :MultipleCursorsFind <C-R>/<CR>
    vnoremap <silent> <M-j> :MultipleCursorsFind <C-R>/<CR>
This allows one to search for the keyword using `*` and turn search results into cursors with `Alt-j`.

==============================================================================
8. Contributing                                *multiple-cursors-contributing*

The project is hosted on Github. Patches, feature requests and suggestions are
always welcome!

Find the latest version of the plugin here:
    http://github.com/terryma/vim-multiple-cursors

==============================================================================
9. License                                          *multiple-cursors-license*

The project is licensed under the MIT license [7]. Copyright 2013 Terry Ma

==============================================================================
10. Credit                                           *multiple-cursors-credit*

The plugin is obviously inspired by Sublime Text's awesome multiple selection
[6] feature. Some inspiration was also taken from Emac's multiple cursors [8]
implementation.

==============================================================================
10. References                                    *multiple-cursors-references*

[1] https://github.com/paradigm/vim-multicursor
[2] https://github.com/felixr/vim-multiedit
[3] https://github.com/hlissner/vim-multiedit
[4] https://github.com/adinapoli/vim-markmultiple
[5] https://github.com/AndrewRadev/multichange.vim
[6] http://www.sublimetext.com/docs/2/multiple_selection_with_the_keyboard.html
[7] http://opensource.org/licenses/MIT
[8] https://github.com/magnars/multiple-cursors.el
[9] http://vim.wikia.com/wiki/Get_Alt_key_to_work_in_terminal
[10] https://code.google.com/p/macvim

 vim:tw=78:sw=4:ft=help:norl: