diff --git a/README b/README new file mode 100644 index 0000000..9e32c23 --- /dev/null +++ b/README @@ -0,0 +1,604 @@ +*delimitMate* Trying to keep those beasts at bay! v2.2 *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| + 2.6 FileType based configuration_______|delimitMateFileType| + 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 + ==================== + ( | (|) + –––––––––|–––––––––– + () | ()| + –––––––––|–––––––––– + ( | ()| +< +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 + ============================ + (|) | ( + | | + | ) +< + +NOTE that the expansion of will brake the redo command. + +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. When +expansions are enabled, will also delete the expansions. NOTE that +deleting 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 + ============================================== + | call expand(|) | call expand| + ---------|-------------------|----------------- + | call expand( | ) | call expand(|) + ---------|-------------------|----------------- + | 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. +NOTE that this feature brakes the redo command and 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'| +< +------------------------------------------------------------------------------ + 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 if you use buffer variables (|b:vars|) to set global settings in +your vimrc, those settings will be set for the first buffer, but they'll be +ignored for new buffers and default values will be set. +============================================================================== + 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. +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 . 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. + +------------------------------------------------------------------------------ +: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* + +------------------------------------------------------------------------------ +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.2 2010-05-20 * Current release: + - Added command to switch the plug-in on and off. + - Fix: some problems with , and . + - 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. + - 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: