" File: imaps.vim " Authors: Srinath Avadhanula " Benji Fisher " " WWW: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vim-latex/vimfiles/plugin/imaps.vim?only_with_tag=MAIN " " Description: insert mode template expander with cursor placement " while preserving filetype indentation. " " $Id: imaps.vim,v 1.33.2.1 2003/11/13 09:35:45 srinathava Exp $ " " Documentation: {{{ " " Motivation: " this script provides a way to generate insert mode mappings which do not " suffer from some of the problem of mappings and abbreviations while allowing " cursor placement after the expansion. It can alternatively be thought of as " a template expander. " " Consider an example. If you do " " imap lhs something " " then a mapping is set up. However, there will be the following problems: " 1. the 'ttimeout' option will generally limit how easily you can type the " lhs. if you type the left hand side too slowly, then the mapping will not " be activated. " 2. if you mistype one of the letters of the lhs, then the mapping is " deactivated as soon as you backspace to correct the mistake. " " If, in order to take care of the above problems, you do instead " " iab lhs something " " then the timeout problem is solved and so is the problem of mistyping. " however, abbreviations are only expanded after typing a non-word character. " which causes problems of cursor placement after the expansion and invariably " spurious spaces are inserted. " " Usage Example: " this script attempts to solve all these problems by providing an emulation " of imaps wchich does not suffer from its attendant problems. Because maps " are activated without having to press additional characters, therefore " cursor placement is possible. furthermore, file-type specific indentation is " preserved, because the rhs is expanded as if the rhs is typed in literally " by the user. " " The script already provides some default mappings. each "mapping" is of the " form: " " call IMAP (lhs, rhs, ft) " " Some characters in the RHS have special meaning which help in cursor " placement. " " Example One: " " call IMAP ("bit`", "\\begin{itemize}\\\item <++>\\\end{itemize}<++>", "tex") " " This effectively sets up the map for "bit`" whenever you edit a latex file. " When you type in this sequence of letters, the following text is inserted: " " \begin{itemize} " \item * " \end{itemize}<++> " " where * shows the cursor position. The cursor position after inserting the " text is decided by the position of the first "place-holder". Place holders " are special characters which decide cursor placement and movement. In the " example above, the place holder characters are <+ and +>. After you have typed " in the item, press and you will be taken to the next set of <++>'s. " Therefore by placing the <++> characters appropriately, you can minimize the " use of movement keys. " " NOTE: Set g:Imap_UsePlaceHolders to 0 to disable placeholders altogether. " Set " g:Imap_PlaceHolderStart and g:Imap_PlaceHolderEnd " to something else if you want different place holder characters. " Also, b:Imap_PlaceHolderStart and b:Imap_PlaceHolderEnd override the values " of g:Imap_PlaceHolderStart and g:Imap_PlaceHolderEnd respectively. This is " useful for setting buffer specific place hoders. " " Example Two: " You can use the command to insert dynamic elements such as dates. " call IMAP ('date`', "\=strftime('%b %d %Y')\", '') " " sets up the map for date` to insert the current date. " "--------------------------------------%<-------------------------------------- " Bonus: This script also provides a command Snip which puts tearoff strings, " '----%<----' above and below the visually selected range of lines. The " length of the string is chosen to be equal to the longest line in the range. " Recommended Usage: " '<,'>Snip "--------------------------------------%<-------------------------------------- " }}} " ============================================================================== " Script Options / Variables " ============================================================================== " Options {{{ if !exists('g:Imap_StickyPlaceHolders') let g:Imap_StickyPlaceHolders = 1 endif if !exists('g:Imap_DeleteEmptyPlaceHolders') let g:Imap_DeleteEmptyPlaceHolders = 1 endif " }}} " Variables {{{ " s:LHS_{ft}_{char} will be generated automatically. It will look like " s:LHS_tex_o = 'fo\|foo\|boo' and contain all mapped sequences ending in "o". " s:Map_{ft}_{lhs} will be generated automatically. It will look like " s:Map_c_foo = 'for(<++>; <++>; <++>)', the mapping for "foo". " " }}} " ============================================================================== " functions for easy insert mode mappings. " ============================================================================== " IMAP: Adds a "fake" insert mode mapping. {{{ " For example, doing " IMAP('abc', 'def' ft) " will mean that if the letters abc are pressed in insert mode, then " they will be replaced by def. If ft != '', then the "mapping" will be " specific to the files of type ft. " " Using IMAP has a few advantages over simply doing: " imap abc def " 1. with imap, if you begin typing abc, the cursor will not advance and " long as there is a possible completion, the letters a, b, c will be " displayed on on top of the other. using this function avoids that. " 2. with imap, if a backspace or arrow key is pressed before completing " the word, then the mapping is lost. this function allows movement. " (this ofcourse means that this function is only limited to " left-hand-sides which do not have movement keys or unprintable " characters) " It works by only mapping the last character of the left-hand side. " when this character is typed in, then a reverse lookup is done and if " the previous characters consititute the left hand side of the mapping, " the previously typed characters and erased and the right hand side is " inserted " IMAP: set up a filetype specific mapping. " Description: " "maps" the lhs to rhs in files of type 'ft'. If supplied with 2 " additional arguments, then those are assumed to be the placeholder " characters in rhs. If unspecified, then the placeholder characters " are assumed to be '<+' and '+>' These placeholder characters in " a:rhs are replaced with the users setting of " [bg]:Imap_PlaceHolderStart and [bg]:Imap_PlaceHolderEnd settings. " function! IMAP(lhs, rhs, ft, ...) " Find the place holders to save for IMAP_PutTextWithMovement() . if a:0 < 2 let phs = '<+' let phe = '+>' else let phs = a:1 let phe = a:2 endif let hash = s:Hash(a:lhs) let s:Map_{a:ft}_{hash} = a:rhs let s:phs_{a:ft}_{hash} = phs let s:phe_{a:ft}_{hash} = phe " Add a:lhs to the list of left-hand sides that end with lastLHSChar: let lastLHSChar = a:lhs[strlen(a:lhs)-1] let hash = s:Hash(lastLHSChar) if !exists("s:LHS_" . a:ft . "_" . hash) let s:LHS_{a:ft}_{hash} = escape(a:lhs, '\') else let s:LHS_{a:ft}_{hash} = escape(a:lhs, '\') .'\|'. s:LHS_{a:ft}_{hash} endif " map only the last character of the left-hand side. if lastLHSChar == ' ' let lastLHSChar = '' end exe 'inoremap ' \ escape(lastLHSChar, '|') \ '=LookupCharacter("' . \ escape(lastLHSChar, '\|"') . \ '")' endfunction " }}} " IMAP_list: list the rhs and place holders corresponding to a:lhs {{{ " " Added mainly for debugging purposes, but maybe worth keeping. function! IMAP_list(lhs) let char = a:lhs[strlen(a:lhs)-1] let charHash = s:Hash(char) if exists("s:LHS_" . &ft ."_". charHash) && a:lhs =~ s:LHS_{&ft}_{charHash} let ft = &ft elseif exists("s:LHS__" . charHash) && a:lhs =~ s:LHS__{charHash} let ft = "" else return "" endif let hash = s:Hash(a:lhs) return "rhs = " . s:Map_{ft}_{hash} . " place holders = " . \ s:phs_{ft}_{hash} . " and " . s:phe_{ft}_{hash} endfunction " }}} " LookupCharacter: inserts mapping corresponding to this character {{{ " " This function extracts from s:LHS_{&ft}_{a:char} or s:LHS__{a:char} " the longest lhs matching the current text. Then it replaces lhs with the " corresponding rhs saved in s:Map_{ft}_{lhs} . " The place-holder variables are passed to IMAP_PutTextWithMovement() . function! s:LookupCharacter(char) let charHash = s:Hash(a:char) " The line so far, including the character that triggered this function: let text = strpart(getline("."), 0, col(".")-1) . a:char " Prefer a local map to a global one, even if the local map is shorter. " Is this what we want? Do we care? " Use '\V' (very no-magic) so that only '\' is special, and it was already " escaped when building up s:LHS_{&ft}_{charHash} . if exists("s:LHS_" . &ft . "_" . charHash) \ && text =~ '\V\(' . s:LHS_{&ft}_{charHash} . '\)\$' let ft = &ft elseif exists("s:LHS__" . charHash) \ && text =~ '\V\(' . s:LHS__{charHash} . '\)\$' let ft = "" else " If this is a character which could have been used to trigger an " abbreviation, check if an abbreviation exists. if a:char !~ '\k' let lastword = matchstr(getline('.'), '\k\+$', '') if lastword != '' " An extremeley wierd way to get around the fact that vim " doesn't have the equivalent of the :mapcheck() function for " abbreviations. let _a = @a exec "redir @a | silent! iab ".lastword." | redir END" let abbreviationRHS = matchstr(@a."\n", "\n".'i\s\+'.lastword.'\+\s\+@\?\zs.*\ze'."\n") if @a =~ "No abbreviation found" || abbreviationRHS == "" let @a = _a return a:char endif let @a = _a let abbreviationRHS = escape(abbreviationRHS, '\<"') exec 'let abbreviationRHS = "'.abbreviationRHS.'"' let lhs = lastword.a:char let rhs = abbreviationRHS.a:char let phs = IMAP_GetPlaceHolderStart() let phe = IMAP_GetPlaceHolderEnd() else return a:char endif else return a:char endif endif " Find the longest left-hand side that matches the line so far. " matchstr() returns the match that starts first. This automatically " ensures that the longest LHS is used for the mapping. if !exists('lhs') || !exists('rhs') let lhs = matchstr(text, '\V\(' . s:LHS_{ft}_{charHash} . '\)\$') let hash = s:Hash(lhs) let rhs = s:Map_{ft}_{hash} let phs = s:phs_{ft}_{hash} let phe = s:phe_{ft}_{hash} endif if strlen(lhs) == 0 return a:char endif " enough back-spaces to erase the left-hand side; -1 for the last " character typed: let bs = substitute(strpart(lhs, 1), ".", "\", "g") return bs . IMAP_PutTextWithMovement(rhs, phs, phe) endfunction " }}} " IMAP_PutTextWithMovement: returns the string with movement appended {{{ " Description: " If a:str contains "placeholders", then appends movement commands to " str in a way that the user moves to the first placeholder and enters " insert or select mode. If supplied with 2 additional arguments, then " they are assumed to be the placeholder specs. Otherwise, they are " assumed to be '<+' and '+>'. These placeholder chars are replaced " with the users settings of [bg]:Imap_PlaceHolderStart and " [bg]:Imap_PlaceHolderEnd. function! IMAP_PutTextWithMovement(str, ...) " The placeholders used in the particular input string. These can be " different from what the user wants to use. if a:0 < 2 let phs = '<+' let phe = '+>' else let phs = escape(a:1, '\') let phe = escape(a:2, '\') endif let text = a:str " The user's placeholder settings. let phsUser = IMAP_GetPlaceHolderStart() let pheUser = IMAP_GetPlaceHolderEnd() " Problem: depending on the setting of the 'encoding' option, a character " such as "\xab" may not match itself. We try to get around this by " changing the encoding of all our strings. At the end, we have to " convert text back. let phsEnc = s:Iconv(phs, "encode") let pheEnc = s:Iconv(phe, "encode") let phsUserEnc = s:Iconv(phsUser, "encode") let pheUserEnc = s:Iconv(pheUser, "encode") let textEnc = s:Iconv(text, "encode") if textEnc != text let textEncoded = 1 else let textEncoded = 0 endif let pattern = '\V\(\.\{-}\)' .phs. '\(\.\{-}\)' .phe. '\(\.\*\)' " If there are no placeholders, just return the text. if textEnc !~ pattern call IMAP_Debug('Not getting '.phs.' and '.phe.' in '.textEnc, 'imap') return text endif " Break text up into "initial <+template+> final"; any piece may be empty. let initialEnc = substitute(textEnc, pattern, '\1', '') let templateEnc = substitute(textEnc, pattern, '\2', '') let finalEnc = substitute(textEnc, pattern, '\3', '') " If the user does not want to use placeholders, then remove all but the " first placeholder. " Otherwise, replace all occurences of the placeholders here with the " user's choice of placeholder settings. if exists('g:Imap_UsePlaceHolders') && !g:Imap_UsePlaceHolders let finalEnc = substitute(finalEnc, '\V'.phs.'\.\{-}'.phe, '', 'g') else let finalEnc = substitute(finalEnc, '\V'.phs.'\(\.\{-}\)'.phe, \ phsUserEnc.'\1'.pheUserEnc, 'g') endif " The substitutions are done, so convert back, if necessary. if textEncoded let initial = s:Iconv(initialEnc, "decode") let template = s:Iconv(templateEnc, "decode") let final = s:Iconv(finalEnc, "decode") else let initial = initialEnc let template = templateEnc let final = finalEnc endif " Build up the text to insert: " 1. the initial text plus an extra character; " 2. go to Normal mode with , so it works even if 'insertmode' " is set, and mark the position; " 3. replace the extra character with tamplate and final; " 4. back to Normal mode and restore the cursor position; " 5. call IMAP_Jumpfunc(). let template = phsUser . template . pheUser " Old trick: insert and delete a character to get the same behavior at " start, middle, or end of line and on empty lines. let text = initial . "X\\:call IMAP_Mark('set')\\"_s" let text = text . template . final let text = text . "\\:call IMAP_Mark('go')\" let text = text . "i\=IMAP_Jumpfunc('', 1)\" return text endfunction " }}} " IMAP_Jumpfunc: takes user to next <+place-holder+> {{{ " Author: Luc Hermitte " Arguments: " direction: flag for the search() function. If set to '', search forwards, " if 'b', then search backwards. See the {flags} argument of the " |search()| function for valid values. " inclusive: In vim, the search() function is 'exclusive', i.e we always goto " next cursor match even if there is a match starting from the " current cursor position. Setting this argument to 1 makes " IMAP_Jumpfunc() also respect a match at the current cursor " position. 'inclusive'ness is necessary for IMAP() because a " placeholder string can occur at the very beginning of a map which " we want to select. " We use a non-zero value only in special conditions. Most mappings " should use a zero value. function! IMAP_Jumpfunc(direction, inclusive) " The user's placeholder settings. let phsUser = IMAP_GetPlaceHolderStart() let pheUser = IMAP_GetPlaceHolderEnd() let searchString = '' " If this is not an inclusive search or if it is inclusive, but the " current cursor position does not contain a placeholder character, then " search for the placeholder characters. if !a:inclusive || strpart(getline('.'), col('.')-1) !~ '\V\^'.phsUser let searchString = '\V'.phsUser.'\_.\{-}'.pheUser endif " If we didn't find any placeholders return quietly. if searchString != '' && !search(searchString, a:direction) return '' endif " Open any closed folds and make this part of the text visible. silent! foldopen! " Calculate if we have an empty placeholder or if it contains some " description. let template = \ matchstr(strpart(getline('.'), col('.')-1), \ '\V\^'.phsUser.'\zs\.\{-}\ze\('.pheUser.'\|\$\)') let placeHolderEmpty = !strlen(template) " If we are selecting in exclusive mode, then we need to move one step to " the right let extramove = '' if &selection == 'exclusive' let extramove = 'l' endif " Select till the end placeholder character. let movement = "\v/\\V".pheUser."/e\".extramove " First remember what the search pattern was. s:RemoveLastHistoryItem will " reset @/ to this pattern so we do not create new highlighting. let g:Tex_LastSearchPattern = @/ " Now either goto insert mode or select mode. if placeHolderEmpty && g:Imap_DeleteEmptyPlaceHolders " delete the empty placeholder into the blackhole. return movement."\"_c\:".s:RemoveLastHistoryItem."\" else return movement."\\:".s:RemoveLastHistoryItem."\gv\" endif endfunction " }}} " Maps for IMAP_Jumpfunc {{{ " " These mappings use and thus provide for easy user customization. When " the user wants to map some other key to jump forward, he can do for " instance: " nmap ,f IMAP_JumpForward " etc. " jumping forward and back in insert mode. imap IMAP_JumpForward =IMAP_Jumpfunc('', 0) imap IMAP_JumpBack =IMAP_Jumpfunc('b', 0) " jumping in normal mode nmap IMAP_JumpForward i=IMAP_Jumpfunc('', 0) nmap IMAP_JumpBack i=IMAP_Jumpfunc('b', 0) " deleting the present selection and then jumping forward. vmap IMAP_DeleteAndJumpForward "_i=IMAP_Jumpfunc('', 0) vmap IMAP_DeleteAndJumpBack "_i=IMAP_Jumpfunc('b', 0) " jumping forward without deleting present selection. vmap IMAP_JumpForward i=IMAP_Jumpfunc('', 0) vmap IMAP_JumpBack `=IMAP_Jumpfunc('b', 0) " }}} " Default maps for IMAP_Jumpfunc {{{ " map only if there is no mapping already. allows for user customization. " NOTE: Default mappings for jumping to the previous placeholder are not " provided. It is assumed that if the user will create such mappings " hself if e so desires. if !hasmapto('IMAP_JumpForward', 'i') imap IMAP_JumpForward endif if !hasmapto('IMAP_JumpForward', 'n') nmap IMAP_JumpForward endif if exists('g:Imap_StickyPlaceHolders') && g:Imap_StickyPlaceHolders if !hasmapto('IMAP_JumpForward', 'v') vmap IMAP_JumpForward endif else if !hasmapto('IMAP_DeleteAndJumpForward', 'v') vmap IMAP_DeleteAndJumpForward endif endif " }}} nmap