updated for version 7.0189

runtime/doc/insert.txt

@@ -1,4 +1,4 @@
-*insert.txt*    For Vim version 7.0aa.  Last change: 2006 Jan 08
+*insert.txt*    For Vim version 7.0aa.  Last change: 2006 Jan 29
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -871,8 +871,8 @@ CTRL-X CTRL-V		Guess what kind of item is in front of the cursor and
 User defined completion					*compl-function*
 
 Completion is done by a function that can be defined by the user with the
-'completefunc' option.  See the 'completefunc' help for how the function
-is called and an example.
+'completefunc' option.  See below for how the function is called and an
+example |complete-functions|.
 
 							*i_CTRL-X_CTRL-U*
 CTRL-X CTRL-U		Guess what kind of item is in front of the cursor and
@@ -890,7 +890,7 @@ Omni completion						*compl-omni*
 Completion is done by a function that can be defined by the user with the
 'omnifunc' option.  This is to be used for filetype-specific completion.
 
-See the 'completefunc' help for how the function is called and an example.
+See below for how the function is called and an example |complete-functions|.
 For remarks about specific filetypes see |compl-omni-filetypes|.
 
 							*i_CTRL-X_CTRL-O*
@@ -952,6 +952,94 @@ CTRL-P			Find previous match for words that start with the
 			other contexts unless a double CTRL-X is used.
 
 
+FUNCTIONS FOR FINDING COMPLETIONS			*complete-functions*
+
+This applies to 'completefunc' and 'omnifunc'.
+
+The function will be invoked with two arguments.  First the function is called
+to find the start of the text to be completed.  Secondly the function is
+called to actually find the matches.
+
+On the first invocation the arguments are:
+   a:findstart  1
+   a:base	empty
+
+The function must return the column of where the completion starts.  It must
+be a number between zero and the cursor column "col('.')".  This involves
+looking at the characters just before the cursor and including those
+characters that could be part of the completed item.  The text between this
+column and the cursor column will be replaced with the matches.  Return -1 if
+no completion can be done.
+
+On the second invocation the arguments are:
+   a:findstart  0
+   a:base	the text with which matches should match, what was
+		located in the first call (can be empty)
+
+The function must return a List with the matching words.  These matches
+usually include the "a:base" text.  When there are no matches return an empty
+List.  When one of the items in the list cannot be used as a string (e.g., a
+Dictionary) then an error message is given and further items in the list are
+not used.
+
+When searching for matches takes some time call |complete_add()| to add each
+match to the total list.  These matches should then not appear in the returned
+list!  Call |complete_check()| now and then to allow the user to press a key
+while still searching for matches.  Stop searching when it returns non-zero.
+
+The function may move the cursor, it is restored afterwards.  This option
+cannot be set from a |modeline| or in the |sandbox|, for security reasons.
+
+An example that completes the names of the months: >
+	fun! CompleteMonths(findstart, base)
+	  if a:findstart
+	    " locate the start of the word
+	    let line = getline('.')
+	    let start = col('.') - 1
+	    while start > 0 && line[start - 1] =~ '\a'
+	      let start -= 1
+	    endwhile
+	    return start
+	  else
+	    " find months matching with "a:base"
+	    let res = []
+	    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
+	      if m =~ '^' . a:base
+		call add(res, m)
+	      endif
+	    endfor
+	    return res
+	  endif
+	endfun
+	set completefunc=CompleteMonths
+<
+The same, but now pretending searching for matches is slow: >
+	fun! CompleteMonths(findstart, base)
+	  if a:findstart
+	    " locate the start of the word
+	    let line = getline('.')
+	    let start = col('.') - 1
+	    while start > 0 && line[start - 1] =~ '\a'
+	      let start -= 1
+	    endwhile
+	    return start
+	  else
+	    " find months matching with "a:base"
+	    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
+	      if m =~ '^' . a:base
+		call complete_add(m)
+	      endif
+	      sleep 300m	" simulate searching for next match
+	      if complete_check()
+		break
+	      endif
+	    endfor
+	    return []
+	  endif
+	endfun
+	set completefunc=CompleteMonths
+<
+
 INSERT COMPLETION POPUP MENU				*ins-completion-menu*
 							*popupmenu-completion*
 Vim can display the matches in a simplistic popup menu.