*delimitMate* Trying to keep those beasts at bay! v.2.0 *delimitMate.txt* ========================================================================= ~ ==== ========= ========================== ===== ===================== ~ ==== ========= ========================== === ===================== ~ ==== ========= ===================== === = = ========== ========= ~ ==== === === == == = = === == == == == === === === == ~ == == = == ====== ======= === ===== == = === === = = ~ = = == == == == = = == === === ===== ===== === === = ~ = = == ===== == == = = == === === ===== === === === ==== ~ = = == = == == == = = == === === ===== == = === === = = ~ == === === == == = = == === == ===== === === === == ~ ========================================================================= ~ REFERENCE MANUAL * ============================================================================== 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| 3. Customization___________________________|delimitMateOptions| 3.1 Option 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* The delimitMate plugin tries to provide some not so dumb help in the work with delimiters (brackets, quotes, etc.), with some optional auto-completions and expansions. When automatic closing is enabled, if an opening delimiter is inserted delimitMate inserts the closing pair and places the cursor between them. When automatic closing is disabled, no closing delimiters is inserted by delimitMate, but if a pair of delimiters is typed, the cursor is placed in the middle. Also, to get out of a pair of delimiters just type shift+tab or the right delimiter and the cursor will jump to the right. If the cursor is inside an empty pair of delimiters, typing will insert two spaces and the cursor will be placed in the middle; typing will insert to car retunrs and place the cursor in the middle line, between the delimiters. All of the operations are undo/redo-wise safe. ============================================================================== 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 ==================== ( | (|) –––––––––|–––––––––– () | ()| –––––––––|–––––––––– ( | ()| < Without auto-close: > Type | You get ===================== () | (|) –––––––––-|–––––––––– ()) | ()| –––––––––-|–––––––––– () | ()| < ------------------------------------------------------------------------------ 2.2 EXPANSION OF SPACE AND CAR RETURN *delimitMateExpansion* When the cursor is inside an empty pair of delimiters, and can be expanded, see |'delimitMate_expand_space'| and |'delimitMate_expand_cr'|: Expand to: > | You get ==================================== (|) | ( | ) < Expand to: > | You get ============================ (|) | ( | | | ) < Since and 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. If you type shift + backspace instead, only the closing delimiter will be deleted. e.g. typing at the "|": > What | Before | After ============================================== | call expand(|) | call expand| ---------|------------------|----------------- | 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. This feature doesn't currently work on blockwise visual mode, any suggestions will be 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'| < ============================================================================== 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 . |'delimitMate_expand_space'| Turns on/off the expansion of . |'delimitMate_excluded_ft'| Turns off the script for the given file types. |'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. Local options take precedence over global ones and can be used along with autocmd to modify delimitMate's behavior for specific file types. ------------------------------------------------------------------------------ *'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 = "(:),[:],{:},<:>" 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 . Read |delimitMateExpansion| for details. e.g.: > let b:delimitMate_expand_cr = "\\\" au FileType mail let b:delimitMate_expand_cr = "\" < ------------------------------------------------------------------------------ *'delimitMate_expand_space'* *'b:delimitMate_expand_space'* Values: A key mapping. ~ Default: "\" ~ This option turns on/off the expansion of . Read |delimitMateExpansion| for details. e.g.: > let delimitMate_expand_space = "\\\" au FileType tcl let b:delimitMate_expand_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_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. ------------------------------------------------------------------------------ :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* ------------------------------------------------------------------------------ delimitMate_WithinEmptyPair() *delimitMate_WithinEmptyPair* Returns 1 if the cursor is inside an empty pair, 0 otherwise. ------------------------------------------------------------------------------ DelimitMate_ExpandReturn() *DelimitMate_ExpandReturn()* Returns the expansion for . e.g.: This mapping could be used to select an item on a pop-up menu or expand inside an empty pair: > inoremap pumvisible() ? "\" : \ DelimitMate_WithinEmptyPair ? \ DelimitMate_ExpandReturn() : "\" < ------------------------------------------------------------------------------ DelimitMate_ExpandSpace() *DelimitMate_ExpandSpace()* Returns the expansion for . e.g.: > inoremap DelimitMate_WithinEmptyPair() ? \ DelimitMate_ExpandSpace() : "\" < ------------------------------------------------------------------------------ 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() *DelimitMate_JumpAny()* This function returns a mapping that will make the cursor jump to the right. e.g.: You can use this to create your own mapping to jump over any delimiter. > inoremap

DelimitMate_ShouldJump() ? \ DelimitMate_JumpAny() : "\" < ============================================================================== 6. TODO LIST *delimitMateTodo* - Automatic set-up by file type. - Make visual wrapping work on blockwise visual mode. - Limit behaviour by region. ============================================================================== 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.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. - jumps out of any empty pair. - and 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. - 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. |---------|------------|-----------------------------------------------------| ... |"| _ _ . . ___ ~ o,*,(o o) _|_|_ o' \,=./ `o . .:::. /_\ `* ~ 8(o o)(_)Ooo (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: