*substitute.txt*    Mappings for performing substitution                2010-12-29
==============================================================================
Author:  Anders Thøgersen <anders [at] bladre.dk>
Version: 1.3
==============================================================================
Contents

    1. Purpose..............: |substitute-purpose|
    2. Mappings.............: |substitute-maps|
    3. Configuration........: |substitute-config|
    4. History..............: |substitute-history|

==============================================================================
1. Purpose                                                  *substitute-purpose*

The substitute.vim script provides shortcuts for replacing the text under the
cursor, or visually selected text in the current buffer.  It is a shortcut to
the vim built in substitute command; see |:substitute|.

There are two mappings defined: one which will replace text across the whole
file without prompting, and one which will prompt for every replacement.

It should be noted that this script modifies a register when one of the
mappings is executed.  This register defaults to "9 but it can be changed; see
|substitute-config|.

==============================================================================
2. Key mappings                                                *substitute-maps*

substitute.vim provides the following two mappings for both visual and normal
mode:

   ;;  Run |:substitute| on the current buffer without prompting.

   ;'  The same, only prompt for each.

   ';  Perform substitution on the lines that match a *multi-repeat*
       expression, prompting for each.


These mappings can be changed as specified in the following section.

It is also possible to press <C-R><C-R> while in command line mode to insert
the text that is replaced into the commandline.

==============================================================================
3. Configuration                                             *substitute-config*

To change the default mappings to mappings that you like better you can change
the value of the following variables before sourcing the substitute.vim
script. It defaults to:

                                                             *substitute-prompt*
   let g:substitute_PromptMap = ";'"

This variable contains the key sequence for invoking substitution that should
prompt each time a match is found:

                                                           *substitute-noprompt*
   let g:substitute_NoPromptMap = ';;'

This variable specifies the key sequence for invoking substitution without
prompting.

                                                             *substitute-global*
   let g:substitute_GlobalMap = "';"

The key sequence to start a g//s/<word>//gc command.

                                                           *substitute-register*
To change the register that is overwritten when executing one of the provided
mappings you can change the value of this variable:

   let g:substitute_Register = '9'

                                                         *substitute-singleword*
When the word under the cursor is less than or equal to this size surround it
with \< and \> in the substitution. The default is:

   let g:substitute_SingleWordSize = 3

Disable by setting the value to -1.

==============================================================================
4. History
   1.3  - Minor fixes

   1.2  - Hacked in SingleWordSize and GlobalMap.

   1.1  - Added use of GetLatestVimScripts and fixed a small bug.

   1.04 - Added a separate helpfile and the possibility of customizing
          mappings and the register that the script uses.

   1.03 - Simplified the mapping a bit. Marking register ' was not needed.

   1.02 - Changed the meaning of the ;' mapping, and added <unique> to the map
          definitions.  Added the Escape function so $ and ^ are only escaped
          when they appear at the beginning, or at the end.  Also added
          cpoptions check and <SID> stuff.

   1.01 - Removed unuseful mapcheck.

==============================================================================
$Id$
==============================================================================
vim:tw=78:ft=help