*multiselect.txt*  Create multiple selections and operate
                    Requires Vim 7.0
            Last Change: 08-Sep-2006 @ 22:18
          Since Version: 2.0
               Revision: 1.0.0
         Plugin Version: 2.2
                 Author: Hari Krishna Dara (hari_vim at yahoo dot com)

                                            *multiselect-introduction*
                                            *multiselect-plugin*
This plugin extends the Vim's visual mode functionality by allowing you to
select non-contiguous regions and execute commands on them. It makes it really
easy to select multiple regions using mouse, as you can use Ctrl+Mouse
combination just like in MS Word. There are a number of operations to very
easily manipulate selections such as modifying the regions
(add/delete/inverte/clear), hiding, refreshing, saving and restoring etc. You
can execute both normal and :ex mode commands in one shot on all the regions.
The selections are also local to the buffer, so you can have separate selectins
for each buffer.

==============================================================================
OVERVIEW                                    *multiselect-overview*

|multiselect-installation|     How to install the plugin.

|multiselect-usage|            A brief usage to get you quickly started.

|multiselect-commands|         A description of various ex commands and their
                               mappings that will be defined by the plugin.

|multiselect-settings|         An explanation of settings.

|multiselect-API|              New API provided by the plugin (experimental).

|multiselect-tips|             Some useful tips.

|multiselect-limitations|      Current limitations of the plugin.

|multiselect-todo|             Some TODO items.

|multiselect-changes|          A change list for current version from previous
                               versions.

|multiselect-acknowledgements| Acknowledgements.

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

                                            *multiselect-installation*
    - To install, download the latest versions of these two plugins:
        multiselect: http://www.vim.org/script.php?script_id=953
        genutils:  http://vim.sourceforge.net/script.php?script_id=197
    - Extract the zip archives in to your runtime directory (.vim or vimfiles
      under your HOME directory).
    - Start a new instance or go to an existing instance of vim.
    - Execute:
>
        :helpt <your runtime directory>/doc
<
      This should generate the help tags for the selectbuf plugin help.
    - Take a look at the |multiselect-settings| to change any default
      configuration and behavior.

Later, if you need to temporarily disable the plugin without needing to remove
the file or move it into a different directory, you can set the
loaded_multiselect variable in your vimrc. You can also set the
no_multiselect_maps to disable just the mappings defined in this plugin or
no_plugin_maps to disable mappings in all the plugins (provided they honor this
setting), in your vimrc.
==============================================================================

                                            *multiselect-usage*
Once installed, the features are available in all the buffers. To create
selection regions you can use mouse or keyboard.
    - To use mouse, hold Ctrl key and make a visual selection using the
      LeftMouse button just like you normally do. Once the mouse button is
      released, the selection gets automatically added as a new selection
      region. If you are selecting only one line, you can release the mouse
      button without having to drag.
    - To use keyboard, make a visual selection using |visual-mode| commands or
      mouse and press <Enter> to create a new region out of it. The <Enter> (or
      <CR>) key is mapped only if it is not already mapped in visual mode. The
      cursor is placed in the direction of the selection such that it is easier
      to continue moving the cursor for making further selections.
    - To clear part or the whole of a region from selection, repeat the
      same exact procedure over that region. You can however mix mouse and
      keyboard usage. The procedure is equivalent to running the |:MSInvert|
      command as describe in |multiselect-commands|.
    - Once you repeat the procedure to create all the regions that you need to
      act on, use one of the |:MSExecCmd| or |:MSExecNormalCmd| (or one of their
      equivalent maps) to execute commands on them. Ex:
        - Delete all the lines in the current selections >
            MSExecCmd d
<       - Convert all the characters in the current selections to upper case. >
            MSExecNormalCmd gU
<   - Use |:MSClear| (or its map) to clear the selection.
==============================================================================

                                            *multiselect-commands*
Here is a set of mappings (with applicable modes) and the equivalent command
that (in parenthesis) this plugin defines for each operation (for brevity,
"Mapping Name" does not include the common prefix of <Plug>MS and defaults do
not include the common prefix of <Leader>):

                                            *:MSAdd*      *:MSDelete* *:MSClear*
                                            *:MSRestore*  *:MSRefresh* *:MSHide*
                                            *:MSInvert*   *:MSShow*    
                                            *:MSNext*     *:MSPrev*
                                            *:MSMatchAdd* *:MSVMatchAdd*
                                            *:MSExecCmd*  *:MSExecNormalCmd*    
     Mapping Name           Default Mode Description~
     AddSelection               msa  n,v Add current selection to the
                                         selection list (MSAdd).
     DeleteSelection            msd  n   Delete current selection (MSDelete).
     ClearSelection             msc  n,v Clear selections in the given range or
                                         the entire buffer (MSClear).
     RestoreSelections          msr  n   Restore previous state of the
                                         selections (MSRestore). After a
                                         ClearSelection, this works like |gv|.
     RefreshSelections          msf  n   Refresh/Redraw selections (MSRefresh).
     HideSelections             msh  n   Hide the selections (MSHide). Use
                                         MSRefresh to show the sections again.
     InvertSelections           msi  n,v Invert the entire or selected
                                         selection (MSInvert).
                             <CR>/   v   If not in use.
                             <Enter>     
                          Ctrl+LeftMouse Invert selections using mouse.
     ExecCmdOnSelection         ms:  n   Execute a ex mode command on all the
                                         selections (MSExecCmd).
     ExecNormalCmdOnSelection   msn  n   Execute a normal mode command on all
                                         the selections (MSExecNormalCmd).
     ShowSelections             mss  n   Dump all the current selections on
                                         the screen as "startline,endline"
                                         pairs (MSShow).
     NextSelection              ms]  n   Take cursor to the next selection
                                         (MSNext).
     PrevSelection              ms[  n   Take cursor to the previous selection
                                         (MSPrev).
     MatchAddSelection          msm  n,v Add matched lines to the selection
                                         (MSMatchAdd).
     VMatchAddSelection         msv  n,v Add unmatched lines to the selection
                                         (MSVMatchAdd).

Note that the ex-mode commands that work on selections can also take
arbitrary ranges (see |:range|).

If you feel that the default mappings defined by the plugin are too long,
consider installing my execmap.vim plugin from vim.org scripts section. It can
be downloaded from: http://www.vim.org/script.php?script_id=598. It makes
execution of long normal-mode commands much easier.

The MSMatchAdd and MSVMatchAdd commands are useful to create selection regions
in one-shot by using a matching pattern as a criterion. See below for additional
matching criteria. Ex:
    - Add all the lines that have "public" to the selection. >
        MSMatchAdd public
<
                                            *:MSMatchAddBySynGroup*
                                            *:MSVMatchAddBySynGroup*
                                            *:MSMatchAddByDiffHlGroup*
                                            *:MSVMatchAddByDiffHlGroup*
     Ex Command                   Description~
     MSMatchAddBySynGroup         Add lines in the specified syntax group to the
                                  selection.
     MSVMatchAddBySynGroup        Add lines not in the specified syntax group to
                                  the selection.
     MSMatchAddByDiffHlGroup      Add lines in the specified diff highlighting
                                  group to the selection.
     MSVMatchAddByDiffHlGroup     Add lines not in the specified diff highlighting
                                  group to the selection.

You can use MSMatchAddBySynGroup and MSVMatchAddBySynGroup commands to specify a
syntax group as a matching criterion and MSMatchAddByDiffHlGroup and
MSVMatchAddByDiffHlGroup to specify |diff_hlID()| as matching criterion. The
group is checked on the last character of every line in the specified range and
if it is same as the specified group, then the line is added/removed to/from the
new selection. If you want a different column to be considered for determining
the group, then you can create your own version of these commands easily by
using the MSAddSelectionsByExpr() function as described below. Ex:
    - Add all the lines that are in "Comment" syntax group to the selection. >
        MSMatchAddBySynGroup Comment
<   - Add all the lines that are in the "DiffAdd" highlighting group to the
      selection. >
        MSMatchAddByDiffHlGroup DiffAdd
<
==============================================================================

                                            *multiselect-settings*
- Customize MultiSelections highlighting group if you don't like the
  default "reverse" video. E.g.: >

    hi MultiSelections guifg=grey90 guibg=black
<
  This setting is used only if have |multiselUseSynHi| set.
                                            *no_multiselect_mousemaps*
- To disable mouse mappings without disabling the rest, use
  g:no_multiselect_mousemaps setting.
                                            *multiselUseSynHi*
- Set g:multiselUseSynHi to 1 if you prefer using syntax highlighting over
  :match highlight to highlight the selections. They both have advantages
  and disadvantages, e.g., you can have multiple syntax highlighting rules
  coexist, but only one :match highlighting can exist at any time in a
  window (so if you have other plugins that depend on :match highlighting,
  then you have a collision). However, highlighting selections by syntax
  rules is not perfected yet, so in most cases, :match highlighting should
  work better than syntax highlighting.
                                            *multiselAbortOnErrors*
- Set g:multiselAbortOnErrors to 0 if you don't want the plugin to abort
  on errors while executing commands on the selections. Alternatively, you
  can pass in the appropriate flag/option to avoid generating an error
  (such as 'e' flag to :substitute or :silent command in general)
                                            *multiselMouseSelAddMod*
- If you would like to change the modifiers that are used to add
  selections through mouse (from the default Ctrl), use
  g:multiselMouseSelAddMod variable. E.g. to use Alt+Shift (or Meta+Shift)
  as the modifiers,

    let g:multiselMouseSelAddMod = 'M-S-'

  You can also change the mouse key that is to be used (Right instead of
  Left, e.g.) by setting the g:multiselMouseSelAddKey variable. E.g. to
  use Alt+RightMouse, you would set:

    let g:multiselMouseSelAddMod = 'M-'
    let g:multiselMouseSelAddKey = 'Right'

  You could also remove the need to press modifiers by setting
  g:multiselMouseSelAddMod to an empty string. You will then essentially replace
  the normal Vim selection mechanism with that of the plugin.
  
  Modifying this variable at :ex prompt doesn't have any impact on the current
  session, unless you reload the plugin. To reload, first unlet the
  g:loaded_multiselect variable >
    :unlet g:loaded_multiselect
< and execute a :runtime command as: >
    :runtime plugin/multiselect.vim
<                                           *multiselQuickSelAdds*
- Use g:multiselQuickSelAdds to have the mouse selection or <Enter> on visual
  selection execute |:MSAdd| instead of the default |:MSInvert|.
==============================================================================

                                        *multiselect-API*
- To allow other plugins access selections programmatically, the plugin
  defines the following global functions (with java-method-like prototypes):

      " Number of selections that exist in the current buffer.
      int     MSNumberOfSelections()
      " Returns true if there are any selections made.
      boolean MSSelectionExists()
      " First line in the given selection.
      int     MSFL(List sel)
      " Last line in the given selection.
      int     MSLL(List sel)
      " Returns the selections for the current buffer. The selections can also
      "   be accessed directly in b:multiselRanges, but it is safer to use this
      "   function.
      List    MSGetSelections()
      " If the plugin is currently executing a command on the selection. Useful
      "   for code that can be executed recursively (autocommands etc.)
      boolean MSIsExecuting()
      " Return the index of the selection containing the linenr. For dir pass:
      "   0 - Find the selection containing the line.
      "   1 - Find the next selection.
      "  -1 - Find the previous selection.
      int     MSFindSelection(linenr, dir)

The selections are stored as a Vim7 List in the buffer local variable called
b:multiselRanges (which may not exist if there are no selections yet in the
current buffer). The format of each selection item is itself a List of start and
end line numbers of the selection, but it recommended to use the FL() and LL()
functions to access them, as the structure is subject to change in the future.

If your plugin depends on the existence of multiselect, it is recommended to
check the compatibility by comparing the value of loaded_multiselect with what
is expected. The format of this value is exactly same as the |v:version|. Ex: >
    if !exists('loaded_multiselect')
      runtime plugin/multiselect.vim
    endif
    if exists('loaded_multiselect') && loaded_multiselect < 201
      echomsg 'MyPlugin: You need a newer version of multiselect.vim plugin'
    endif
<
There is also a global function called multiselect#AddSelectionsByExpr() that
can be used to create selections programmatically by using simple boolean
expression. This can be used by users to create additional commands such as
MSMatchAddBySynGroup, but with your own condition. The function executes the
passed in expression for every line, after setting the current on the line and
based on the boolean result, includes or excludes a line from the lines to be
added to selections. The prototype of this function is: >

  function! multiselect#AddSelectionsByExpr(int fline, int lline,
                                  String expr, boolean negate, ...)
<
You can pass in additional user arguments to the function, which are
accessible to the expression as a:1, a:2 etc. (see |:function|)
==============================================================================

                                            *multiselect-tips*
- You may add the following mapping in your vimrc to use <Enter> key to quickly
  make multiple single-line selections in normal mode. >

      nnoremap <Enter> :MSAdd<CR>

< You can also substitute <Space> for <Enter>
- In a |vimdiff| window, if you want to execute some commands only on, say,
  lines that are added, then you can use the |:MSMatchAddByDiffHlGroup| command
  to first select the lines as below: >

        MSMatchAddByDiffHlGroup DiffAdd

< You can then execute commands such as a substitution: >

        MSExecCmd s/old/new/g
<
======.=====================================================================

                                            *multiselect-limitations*
- Currently it is limited to the visual-by-line mode. There are other
  limitations that exist, e.g., the selection is remembered by line
  numbers, so insertions and deletions above the selections will not be
  automatically taken care of.
==============================================================================

                                            *multiselect-todo*
- While executing commands on multiple ranges, there should be a way to execute
  at least normal commands on each line in the range instead of each range
  (useful for running on plugin windows).
- Implement yank and paste selections (\msy, \msp), but how should they really
  work?
- Support different visual modes. The block mode could be quite complicated to
  implement.
==============================================================================

                                            *multiselect-changes*

                                            *multiselect-changes-2.1*
- Changed public API to not autoload script. It doesn't make sense for public
  API to load the script if it is not already loaded. This will also cause
  problems when the plugin is disabled, but other plugins try to use it.

                                            *multiselect-changes-2.0*
- All the functionality has been rewritten to take advantage of new Vim7
  features such as Lists. The programmatic API is not backwards compatible.
- The plugin is now autoloaded, so it will not be (auto)loaded until you execute
  the first mapping/command. This will help improve the startup time of your Vim
  session.
- Misc. bug fixes have been fixed in the ares of |:MSInvert| and |:MSAdd|.
- The g:multiselTmpMark is no longer supported and required. The plugin now
  uses getpos() and setpos() to avoid overwriting any user marks.
- New setting |g:multiselQuickSelAdds|.
- New commands |:MSMatchAddByDiffHlGroup| and |:MSVMatchAddByDiffHlGroup| to
  select regions in a |vimdiff| window.

                                            *multiselect-changes-1.3*
- New commands MSMatchAddBySynGroup and MSVMatchAddBySynGroup to select lines
  automatically by their syntax group in a given range. Useful to select all
  lines in comments (or more specifically perl pod) etc. and do operations such
  as running a spell check on them.
- New global function MSAddSelectionsByExpr() for creating new commands such as
  MSMatchAddBySynGroup and MSMatchAdd by the user. 

                                            *multiselect-changes-1.2*
- MSInvert command now works better.

                                            *multiselect-changes-1.1*
- Full support for mouse in making multiple selections. Works pretty much like
  in MS word.
- Improved behavior for MSInvert. 

                                            *multiselect-changes-1.0*
- Initial release.
==============================================================================

                                            *multiselect-acknowledgements*
- This plugin is based on the multipleRanges.vim script (vimscript#352)
  version 1.7 by Salman Halim (salmanhalim at hotmail dot com). I first
  started with the idea of adding additional features to this plugin, but
  I quickly realized that implementing many of those ideas will be a lot
  more work unless I use a full featured array functionality, which is why
  I have rewritten it first to use multvals.vim, and it has been subsequently
  rewritten to take advantage of Vim7 Lists. Though most of the code has been
  modified and a lot of new code has been added (so there is hardly any code
  that you would see common, except for some structural similarity), I give a
  lot of credit to Salman Halim for the original ideas and to get me quickly
  started with this new plugin.

 vim6:tw=80:ts=8:ft=help:ai:sw=4:et
