*delimitMate*    Trying to keep those beasts at bay! v2.3.1  *delimitMate.txt*



  MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
  MMMM  MMMMMMMMM  MMMMMMMMMMMMMMMMMMMMMMMMMM  MMMMM  MMMMMMMMMMMMMMMMMMMMM  ~
  MMMM  MMMMMMMMM  MMMMMMMMMMMMMMMMMMMMMMMMMM   MMM   MMMMMMMMMMMMMMMMMMMMM
  MMMM  MMMMMMMMM  MMMMMMMMMMMMMMMMMMMMM  MMM  M   M  MMMMMMMMMM  MMMMMMMMM  ~
  MMMM  MMM   MMM  MM  MM  M  M MMM  MM    MM  MM MM  MMM   MMM    MMM   MM
  MM    MM  M  MM  MMMMMM        MMMMMMM  MMM  MMMMM  MM  M  MMM  MMM  M  M  ~
  M  M  MM     MM  MM  MM  M  M  MM  MMM  MMM  MMMMM  MMMMM  MMM  MMM     M
  M  M  MM  MMMMM  MM  MM  M  M  MM  MMM  MMM  MMMMM  MMM    MMM  MMM  MMMM  ~
  M  M  MM  M  MM  MM  MM  M  M  MM  MMM  MMM  MMMMM  MM  M  MMM  MMM  M  M
  MM    MMM   MMM  MM  MM  M  M  MM  MMM   MM  MMMMM  MMM    MMM   MMM   MM  ~
  MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM



==============================================================================
 0.- CONTENTS                                           *delimitMate-contents*

    1. Introduction____________________________|delimitMateIntro|
    2. Functionality___________________________|delimitMateFunctionality|
        2.1 Automatic closing & exiting________|delimitMateAutoClose|
        2.2 Expansion of space and CR__________|delimitMateExpansion|
        2.3 Backspace__________________________|delimitMateBackspace|
        2.4 Visual wrapping____________________|delimitMateVisualWrapping|
        2.5 Smart Quotes_______________________|delimitMateSmartQuotes|
        2.6 FileType based configuration_______|delimitMateFileType|
        2.7 Syntax awareness___________________|delimitMateSyntax|
    3. Customization___________________________|delimitMateOptions|
        3.1 Options summary____________________|delimitMateOptionSummary|
        3.2 Options details____________________|delimitMateOptionDetails|
    4. Commands________________________________|delimitMateCommands|
    5. Functions_______________________________|delimitMateFunctions|
    6. TODO list_______________________________|delimitMateTodo|
    7. Maintainer______________________________|delimitMateMaintainer|
    8. Credits_________________________________|delimitMateCredits|
    9. History_________________________________|delimitMateHistory|

==============================================================================
 1.- INTRODUCTION                                           *delimitMateIntro*

This plug-in provides automatic closing of quotes, parenthesis, brackets,
etc.; besides some other related features that should make your time in insert
mode a little bit easier.

Most of the features can be modified or disabled permanently, using global
variables, or on a FileType basis, using autocommands. With a couple of
exceptions and limitations, this features don't brake undo, redo or history.

==============================================================================
 2. FUNCTIONALITY                                   *delimitMateFunctionality*

------------------------------------------------------------------------------
   2.1 AUTOMATIC CLOSING AND EXITING                    *delimitMateAutoClose*

With automatic closing enabled, if an opening delimiter is inserted the plugin
inserts the closing delimiter and places the cursor between the pair. With
automatic closing disabled, no closing delimiters is inserted by delimitMate,
but when a pair of delimiters is typed, the cursor is placed in the middle.

When the cursor is inside an empty pair or located next to the left of a
closing delimiter, the cursor is placed outside the pair to the right of the
closing delimiter.

Unless |'delimitMate_matchpairs'| or |'delimitMate_quotes'|are set, this
script uses the values in '&matchpairs' to identify the pairs, and ", ' and `
for quotes respectively.

The following table shows the behaviour, this applies to quotes too (the final
position of the cursor is represented by a "|"):

With auto-close: >
                          Type   |  You get
                        ====================
                           (     |    (|)
                        –––––––––|––––––––––
                           ()    |    ()|
                        –––––––––|––––––––––
                        (<S-Tab> |    ()|
<
Without auto-close: >

                          Type    |  You get
                        =====================
                           ()     |    (|)
                        –––––––––-|––––––––––
                           ())    |    ()|
                        –––––––––-|––––––––––
                        ()<S-Tab> |    ()|
<
------------------------------------------------------------------------------
   2.2 EXPANSION OF SPACE AND CAR RETURN                *delimitMateExpansion*

When the cursor is inside an empty pair of delimiters, <Space> and <CR> can be
expanded, see |'delimitMate_expand_space'| and
|'delimitMate_expand_cr'|:

Expand <Space> to: >

                    <Space><Space><Left>  |  You get
                  ====================================
                              (|)         |    ( | )
<
Expand <CR> to: >

                      <CR><CR><Up>  |  You get
                    ============================
                           (|)      |    (
                                    |    |
                                    |    )
<

NOTE that the expansion of <CR> will brake the redo command.

Since <Space> and <CR> are used everywhere, I have made the functions involved
in expansions global, so they can be used to make custom mappings. Read
|delimitMateFunctions| for more details.

------------------------------------------------------------------------------
   2.3 BACKSPACE                                        *delimitMateBackspace*

If you press backspace inside an empty pair, both delimiters are deleted. When
expansions are enabled, <BS> will also delete the expansions. NOTE that
deleting <CR> expansions will brake the redo command.

If you type shift + backspace instead, only the closing delimiter will be
deleted.

e.g. typing at the "|": >

                  What  |      Before       |      After
               ==============================================
                  <BS>  |  call expand(|)   |  call expand|
               ---------|-------------------|-----------------
                  <BS>  |  call expand( | ) |  call expand(|)
               ---------|-------------------|-----------------
                  <BS>  |  call expand(     |  call expand(|)
                        |  |                |
                        |  )                |
               ---------|-------------------|-----------------
                 <S-BS> |  call expand(|)   |  call expand(|
<

------------------------------------------------------------------------------
   2.4 WRAPPING OF VISUAL SELECTION                *delimitMateVisualWrapping*

When visual mode is active this script allows for the selection to be enclosed
with delimiters. But, since brackets have special meaning in visual mode, a
leader (the value of 'mapleader' by default) should precede the delimiter.
NOTE that this feature brakes the redo command and doesn't currently work on
blockwise visual mode, any suggestions to fix this will be very welcome.

e.g. (selection represented between square brackets): >

                      Selected text    |       After \"
                 =============================================
                  An [absurd] example! | An "absurd" example!
<

------------------------------------------------------------------------------
   2.5 SMART QUOTES                                   *delimitMateSmartQuotes*

Only one quote will be inserted following a quote, a "\" or an alphanumeric
character. This should cover closing quotes, escaped quotes and apostrophes.
Except for apostrophes, this feature can be disabled setting the option
|'delimitMate_smart_quotes'| to 0.

e.g. typing at the "|": >

                     What |    Before    |     After
                  =======================================
                      "   |  "String|    |  "String"|
                      "   |  let i = "|  |  let i = "|"
                      '   |  I|          |  I'|
<
------------------------------------------------------------------------------
   2.6 FILE TYPE BASED CONFIGURATION                     *delimitMateFileType*

delimitMate options can be set globally for all buffers using global
("regular") variables in your |vimrc| file. But |:autocmd| can be used to set
options for specific file types (see |'filetype'|) using buffer variables in
the following way: >

   au FileType mail,text let b:delimitMate_autoclose = 0
         ^       ^           ^            ^            ^
         |       |           |            |            |
         |       |           |            |            - Option value.
         |       |           |            - Option name.
         |       |           - Buffer variable.
         |       - File types for which the option will be set.
         - Don't forget to put this event.
<
NOTE that you should use buffer variables (|b:var|) only to set options with
|:autocmd|, for global options use regular variables (|g:var|) in your vimrc.

------------------------------------------------------------------------------
   2.7 SYNTAX AWARENESS                                    *delimitMateSyntax*

The features of this plug-in might not be always helpful, comments and strings
usualy don't need auto-completion. delimitMate monitors which region is being
edited and if it detects that the cursor is in a comment it'll turn itself off
until the cursor leaves the comment. The excluded regions can be set using the
option |'delimitMate_excluded_regions'|. Read |group-name| for a list of
regions or syntax group names.

NOTE that this feature relies on a proper syntax file for the current file
type, if the appropiate syntax file doesn't define a region, delimitMate won't
know about it.

==============================================================================
 3. CUSTOMIZATION                                         *delimitMateOptions*

You can create your own mappings for some features using the global functions.
Read |DelimitMateFunctions| for more info.

------------------------------------------------------------------------------
   3.1 OPTIONS SUMMARY                              *delimitMateOptionSummary*

The behaviour of this script can be customized setting the following options
in your vimrc file. You can use local options to set the configuration for
specific file types, see |delimitMateOptionDetails| for examples.

|'loaded_delimitMate'|          Turns off the script.

|'delimitMate_autoclose'|       Tells delimitMate whether to automagically
                                insert the closing delimiter.

|'delimitMate_matchpairs'|      Tells delimitMate which characters are
                                matching pairs.

|'delimitMate_quotes'|          Tells delimitMate which quotes should be
                                used.

|'delimitMate_visual_leader'|   Sets the leader to be used in visual mode.

|'delimitMate_expand_cr'|       Turns on/off the expansion of <CR>.

|'delimitMate_expand_space'|    Turns on/off the expansion of <Space>.

|'delimitMate_excluded_ft'|     Turns off the script for the given file types.

|'delimitMate_excluded_regions'|Turns off the script for the given regions or
                                syntax group names.

|'delimitMate_apostrophes'|     Tells delimitMate how it should "fix"
                                balancing of single quotes when used as
                                apostrophes. NOTE: Not needed any more, kept
                                for compatibility with older versions.

|'delimitMate_smart_quotes'|    Turns on/off the "smart quotes" feature.

------------------------------------------------------------------------------
   3.2 OPTIONS DETAILS                              *delimitMateOptionDetails*

Add the shown lines to your vimrc file in order to set the below options.
Buffer variables take precedence over global ones and can be used along with
autocmd to modify delimitMate's behavior for specific file types, read more in
|delimitMateFileType|.

Note: Use buffer variables only to set options for specific file types using
:autocmd, use global variables to set options for every buffer. Read more in
|g:var| and |b:var|.

------------------------------------------------------------------------------
                                                        *'loaded_delimitMate'*
                                                      *'b:loaded_delimitMate'*
This option prevents delimitMate from loading.
e.g.: >
        let loaded_delimitMate = 1
        au FileType mail let b:loaded_delimitMate = 1
<
------------------------------------------------------------------------------
                                                     *'delimitMate_autoclose'*
                                                   *'b:delimitMate_autoclose'*
Values: 0 or 1.                                                              ~
Default: 1                                                                   ~

If this option is set to 0, delimitMate will not add a closing delimiter
automagically. See |delimitMateAutoClose| for details.
e.g.: >
        let delimitMate_autoclose = 0
        au FileType mail let b:delimitMate_autoclose = 0
<
------------------------------------------------------------------------------
                                                    *'delimitMate_matchpairs'*
                                                  *'b:delimitMate_matchpairs'*
Values: A string with |matchpairs| syntax.                                   ~
Default: &matchpairs                                                         ~

Use this option to tell delimitMate which characters should be considered
matching pairs. Read |delimitMateAutoClose| for details.
e.g: >
        let delimitMate_matchpairs = "(:),[:],{:},<:>"
        au FileType vim,html let b:delimitMate_matchpairs = "(:),[:],{:},<:>"
<
------------------------------------------------------------------------------
                                                        *'delimitMate_quotes'*
                                                      *'b:delimitMate_quotes'*
Values: A string of characters separated by spaces.                          ~
Default: "\" ' `"                                                            ~

Use this option to tell delimitMate which characters should be considered as
quotes. Read |delimitMateAutoClose| for details.
e.g.: >
        let b:delimitMate_quotes = "\" ' ` *"
        au FileType html let b:delimitMate_quotes = "\" '"
<
------------------------------------------------------------------------------
                                                 *'delimitMate_visual_leader'*
                                               *'b:delimitMate_visual_leader'*
Values: Any character.                                                       ~
Default: q                                                                   ~

The value of this option will be used to wrap the selection in visual mode
when followed by a delimiter. Read |delimitMateVisualWrap| for details.
e.g: >
        let delimitMate_visual_leader = "f"
        au FileType html let b:delimitMate_visual_leader = "f"
<
------------------------------------------------------------------------------
                                                     *'delimitMate_expand_cr'*
                                                   *'b:delimitMate_expand_cr'*
Values: 1 or 0                                                               ~
Default: 0                                                                   ~

This option turns on/off the expansion of <CR>. Read |delimitMateExpansion|
for details.
e.g.: >
        let b:delimitMate_expand_cr = "\<CR>\<CR>\<Up>"
        au FileType mail let b:delimitMate_expand_cr = "\<CR>"
<
------------------------------------------------------------------------------
                                                  *'delimitMate_expand_space'*
                                                *'b:delimitMate_expand_space'*
Values: A key mapping.                                                       ~
Default: "\<Space>"                                                          ~

This option turns on/off the expansion of <Space>. Read |delimitMateExpansion|
for details.
e.g.: >
        let delimitMate_expand_space = "\<Space>\<Space>\<Left>"
        au FileType tcl let b:delimitMate_expand_space = "\<Space>"
<
------------------------------------------------------------------------------
                                                   *'delimitMate_excluded_ft'*
Values: A string of file type names separated by single commas.              ~
Default: Empty.                                                              ~

This options turns delimitMate off for the listed file types, use this option
only if you don't want any of the features it provides on those file types.
e.g.: >
        let delimitMate_excluded_ft = "mail,txt"
<
------------------------------------------------------------------------------
                                              *'delimitMate_excluded_regions'*
Values: A string of syntax group names names separated by single commas.     ~
Default: Comment                                                             ~

This options turns delimitMate off for the listed regions, read |group-name|
for more info about what is a region.
e.g.: >
        let delimitMate_excluded_regions = "Comments,String"
<
------------------------------------------------------------------------------
                                                   *'delimitMate_apostrophes'*
Values: Strings separated by ":".                                            ~
Default: No longer used.                                                     ~

NOTE: This feature is turned off by default, it's been kept for compatibility
with older version, read |delimitMateSmartQuotes| for details.
If auto-close is enabled, this option tells delimitMate how to try to fix the
balancing of single quotes when used as apostrophes. The values of this option
are strings of text where a single quote would be used as an apostrophe (e.g.:
the "n't" of wouldn't or can't) separated by ":". Set it to an empty string to
disable this feature.
e.g.: >
        let delimitMate_apostrophes = ""
        au FileType tcl let delimitMate_apostrophes = ""
<
==============================================================================
 4. COMMANDS                                             *delimitMateCommands*

------------------------------------------------------------------------------
:DelimitMateReload                                        *:DelimitMateReload*

Re-sets all the mappings used for this script, use it if any option has been
changed or if the filetype option hasn't been set yet.

------------------------------------------------------------------------------
:DelimitMateSwitch                                        *:DelimitMateSwitch*

Switches the plug-in on and off.

------------------------------------------------------------------------------
:DelimitMateTest                                            *:DelimitMateTest*

This command tests every mapping set-up for this script, useful for testing
custom configurations.

The following output corresponds to the default values, it will be different
depending on your configuration. "Open & close:" represents the final result
when the closing delimiter has been inserted, either manually or
automatically, see |delimitMateExpansion|. "Delete:" typing backspace in an
empty pair, see |delimitMateBackspace|. "Exit:" typing a closing delimiter
inside a pair of delimiters, see |delimitMateAutoclose|. "Space:" the
expansion, if any, of space, see |delimitMateExpansion|. "Visual-L",
"Visual-R" and "Visual" shows visual wrapping, see
|delimitMateVisualWrapping|. "Car return:" the expansion of car return, see
|delimitMateExpansion|. The cursor's position at the end of every test is
represented by an "|": >

            * AUTOCLOSE:
            Open & close: (|)
            Delete: |
            Exit: ()|
            Space: ( |)
            Visual-L: (v)
            Visual-R: (v)
            Car return: (
            |)

            Open & close: {|}
            Delete: |
            Exit: {}|
            Space: { |}
            Visual-L: {v}
            Visual-R: {v}
            Car return: {
            |}

            Open & close: [|]
            Delete: |
            Exit: []|
            Space: [ |]
            Visual-L: [v]
            Visual-R: [v]
            Car return: [
            |]

            Open & close: "|"
            Delete: |
            Exit: ""|
            Space: " |"
            Visual: "v"
            Car return: "
            |"

            Open & close: '|'
            Delete: |
            Exit: ''|
            Space: ' |'
            Visual: 'v'
            Car return: '
            |'

            Open & close: `|`
            Delete: |
            Exit: ``|
            Space: ` |`
            Visual: `v`
            Car return: `
            |`
<

==============================================================================
 5. FUNCTIONS                                           *delimitMateFunctions*

Functions should be used enclosed between <C-R>= and <CR>, otherwise they
might not work as expected or at all.

------------------------------------------------------------------------------
delimitMate#WithinEmptyPair()                    *delimitMate_WithinEmptyPair*

Returns 1 if the cursor is inside an empty pair, 0 otherwise.

------------------------------------------------------------------------------
delimitMate#ExpandReturn()                        *delimitMate#ExpandReturn()*

Returns the expansion for <CR> if enabled and inside an empty pair, returns
<CR> otherwise.

e.g.: This mapping could be used to select an item on a pop-up menu or expand
<CR> inside an empty pair: >

        inoremap <expr> <CR> pumvisible() ? "\<c-y>" :
                 \ "\<C-R>=delimitMate#ExpandReturn()\<CR>"
<
------------------------------------------------------------------------------
delimitMate#ExpandSpace()                          *delimitMate#ExpandSpace()*

Returns the expansion for <Space> if enabled and inside an empty pair, returns
<Space> otherwise.
e.g.: >

    inoremap <Space> <C-R>=delimitMate#ExpandSpace()<CR>
<
------------------------------------------------------------------------------
delimitMate#ShouldJump()                            *delimitMate#ShouldJump()*

Returns 1 if there is a closing delimiter or a quote to the right of the
cursor, 0 otherwise.

------------------------------------------------------------------------------
delimitMate#JumpAny(key)                               *delimitMate#JumpAny()*

This function returns a mapping that will make the cursor jump to the right
when delimitMate#ShouldJump() returns 1, returns the argument "key" otherwise.
e.g.: You can use this to create your own mapping to jump over any delimiter.
>
   inoremap <C-Tab> <C-R>=delimitMate#JumpAny("\<S-Tab>")<CR>
<

==============================================================================
 6. TODO LIST                                                *delimitMateTodo*

- Automatic set-up by file type.
- Make visual wrapping work on blockwise visual mode.

==============================================================================
 7. MAINTAINER                                         *delimitMateMaintainer*

Hi there! My name is Israel Chauca F. and I can be reached at:
    mailto:israelchauca@gmail.com

Feel free to send me any suggestions and/or comments about this plugin, I'll
be very pleased to read them.

==============================================================================
 8. CREDITS                                               *delimitMateCredits*

Some of the code that make this script is modified or just shamelessly copied
from the following sources:

   - Ian McCracken
     Post titled: Vim, Part II: Matching Pairs:
     http://concisionandconcinnity.blogspot.com/

   - Aristotle Pagaltzis
     From the comments on the previous blog post and from:
     http://gist.github.com/144619

   - Vim Scripts:
     http://www.vim.org/scripts

This script was inspired by the auto-completion of delimiters of TextMate.

==============================================================================
 9. HISTORY                                               *delimitMateHistory*

  Version      Date      Release notes                                       ~
|---------|------------|-----------------------------------------------------|
    2.3.1   2010-06-06 * Current release:
                         - Fix: an extra <Space> is inserted after <Space>
                           expansion.
|---------|------------|-----------------------------------------------------|
    2.3     2010-06-06 * - Syntax aware: Will turn off when editing comments
                           or other regions, customizable.
                         - Changed format of most mappings.
                         - Fix: <CR> expansion doesn't brake automatic
                           indentation adjustments anymore.
                         - Fix: Arrow keys would insert A, B, C or D instead
                           of moving the cursor when using Vim on a terminal.
|---------|------------|-----------------------------------------------------|
    2.2     2010-05-16 * - Added command to switch the plug-in on and off.
                         - Fix: some problems with <Left>, <Right> and <CR>.
                         - Fix: A small problem when inserting a delimiter at
                           the beginning of the line.
|---------|------------|-----------------------------------------------------|
    2.1     2010-05-10 * - Most of the functions have been moved to an
                           autoload script to avoid loading unnecessary ones.
                         - Fixed a problem with the redo command.
                         - Many small fixes.
|---------|------------|-----------------------------------------------------|
    2.0     2010-04-01 * New features:
                         - All features are redo/undo-wise safe.
                         - A single quote typed after an alphanumeric
                           character is considered an apostrophe and one
                           single quote is inserted.
                         - A quote typed after another quote inserts a single
                           quote and the cursor jumps to the middle.
                         - <S-Tab> jumps out of any empty pair.
                         - <CR> and <Space> expansions are fixed, but the
                           functions used for it are global and can be used in
                           custom mappings. The previous system is still
                           active if you have any of the expansion options
                           set.
                         - <S-Backspace> deletes the closing delimiter.

                         * Fixed bug:
                         - s:vars were being used to store buffer options.

|---------|------------|-----------------------------------------------------|
    1.6     2009-10-10 * Now delimitMate tries to fix the balancing of single
                         quotes when used as apostrophes. You can read
                         |delimitMate_apostrophes| for details.
                         Fixed an error when |b:delimitMate_expand_space|
                         wasn't set but |delimitMate_expand_space| wasn't.

|---------|------------|-----------------------------------------------------|
    1.5     2009-10-05 * Fix: delimitMate should work correctly for files
                         passed as arguments to Vim. Thanks to Ben Beuchler
                         for helping to nail this bug.

|---------|------------|-----------------------------------------------------|
    1.4     2009-09-27 * Fix: delimitMate is now enabled on new buffers even
                         if they don't have set the file type option or were
                         opened directly from the terminal.

|---------|------------|-----------------------------------------------------|
    1.3     2009-09-24 * Now local options can be used along with autocmd
                         for specific file type configurations.
                         Fixes:
                         - Unnamed register content is not lost on visual
                         mode.
                         - Use noremap where appropiate.
                         - Wrapping a single empty line works as expected.

|---------|------------|-----------------------------------------------------|
    1.2     2009-09-07 * Fixes:
                         - When inside nested empty pairs, deleting the
                         innermost left delimiter would delete all right
                         contiguous delimiters.
                         - When inside an empty pair, inserting a left
                         delimiter wouldn't insert the right one, instead
                         the cursor would jump to the right.
                         - New buffer inside the current window wouldn't
                         have the mappings set.

|---------|------------|-----------------------------------------------------|
    1.1     2009-08-25 * Fixed an error that ocurred when mapleader wasn't
                         set and added support for GetLatestScripts
                         auto-detection.

|---------|------------|-----------------------------------------------------|
    1.0     2009-08-23 * Initial upload.

|---------|------------|-----------------------------------------------------|


  `\|||/´         MMM           \|/            www            __^__          ~
   (o o)         (o o)          @ @           (O-O)          /(o o)\\        ~
ooO_(_)_Ooo__ ooO_(_)_Ooo___oOO_(_)_OOo___oOO__(_)__OOo___oOO__(_)__OOo_____ ~
_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|____ ~
__|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_ ~
_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|____ ~

vim:tw=78:ts=8:ft=help:norl:formatoptions+=tcroqn:autoindent:
